EDI Import Export

The EDI Orders app reads CSV files from your suppliers, marketplaces, or ERP system and writes the data straight into your J2Commerce store. Each import template you create targets one kind of data — order statuses, stock levels, prices, customers, products, or product images — and remembers the column mapping, file source, and safety settings so you can run the same import again and again without re-configuring it.

Requirements

• Joomla 6.x
• J2Commerce 6.x
• PHP 8.1 or later

Purchase and Download

This app is a separate add-on available from the J2Commerce Extensions Store. It is not included with the core J2Commerce 6 component.

1. Visit www.j2commerce.com and navigate to Apps.
2. Find EDI Orders, click View Details, then Add to Cart and complete checkout.
3. Go to My Downloads under your profile menu, then click Available Versions -> View Files -> Download Now to save the ZIP file.

Install the App

1. In the Joomla admin, go to System -> Install -> Extensions.
2. Upload the plg_j2commerce_app_edi.zip file using the upload panel, or use Install from URL.
3. Joomla installs and enables the plugin automatically.

Enable the App

1. In the Joomla admin, go to J2Commerce -> Apps.
2. Find EDI Orders in the list. If the status icon shows red, click it to enable the app.

Open the App

Click the EDI Orders title in the Apps list. The app opens with three tabs:

• Dashboard — a summary of recent import runs.
• Templates — where you create and manage import templates.
• Logs — a row-by-row history of what each run imported, skipped, or refused, with reasons.

Creating an Import Template

1. Open the Templates tab and click New.
2. Under Basic Information, give the template a Title and choose an Import Entity — the kind of data this template will write. See Import Entities below.
3. Fill in Import Options, File Source, and CSV Settings for how the file arrives and how it is parsed.
4. Open the Column Mapping step and map each column in your CSV file to a target field. The fields available here change depending on the Import Entity you chose.
5. Save the template.

Import Entities

Choose the Import Entity that matches what your CSV file contains. Each entity only shows the column-mapping targets that make sense for that kind of data.

For Order Shipment, choose the status the order should move to after the tracking number is recorded under Move Order To Status — if you leave this blank, the tracking is saved but the order's status does not change.

For Product Stock Level, turn on Update Stock/Availability Status if you also want a quantity of zero to flip the product to out-of-stock (and a positive quantity to flip it back).

For Customer, choose how new accounts get a password under Password Mode, whether new customers must reset their password on first login, and which customer group new accounts join.

Existing Products (Product, Product Variant, and Product Images)

The Product, Product Variant, and Product Images entities share a set of settings under the Existing Products fieldset:

Product Images always updates an existing product (it never creates one), so it uses its own When Product Images Exist setting instead — see below.

Product Variant

The Product Variant import entity updates existing variants (SKU-level records) — it never creates a new one. Map a column and check it as the Lookup Key against the variant's own SKU; the app finds the matching variant and updates the columns you've mapped onto it.

Narrowing to a Parent Product

You can optionally map a second column to the variant's Product ID field to narrow the match to one parent product. This column accepts either value, and the app detects which one you've supplied:

• A plain number is treated as the literal J2Commerce product ID.
• Anything else is treated as the parent product's own SKU — specifically, the SKU of that product's main (master) variant — and resolved to a product ID automatically. If that SKU matches more than one product, the row is skipped as ambiguous, the same rule Match Products By uses elsewhere.

This is useful when your supplier file identifies the parent product by its own SKU rather than its J2Commerce product ID, so you don't need a separate lookup step to convert one to the other before importing.

Product Images

The Product Images import template attaches a main image, main image alt text, and a list of additional images (with their own alt texts) to products that already exist in your store. It never creates a product. Use a Product template to import your catalog first, then run a Product Images template afterward, using a file with the same SKU or product ID column plus image columns, to attach photos.

How Matching Works

Product Images uses the same Match Products By setting described above (Product ID or SKU). If the SKU or product ID in a row doesn't identify exactly one product, that row is skipped and noted in the log — the app never guesses which product a photo belongs to.

Column Mapping

A Product Images template can map only these four target columns, plus the lookup column (product ID or SKU) used for matching:

Multiple additional images in one column. List more than one additional image in a single CSV cell using the Additional Images Separator (default |, pipe) — for example: photo2.jpg|photo3.jpg. Alternatively, map several CSV columns to additional_images (and the matching alt columns to additional_images_alt) instead of using a separator; the app reads them in mapping order.

If you supply fewer alt texts than images, the missing ones fall back to the product's title. Extra alt texts with no matching image are ignored.

Updating only alt text. You can map main_image_alt and/or additional_images_alt on their own, without mapping the matching image column at all. The app updates just the alt text on the product's existing images and leaves the image files themselves untouched — a quick way to fix alt text across your catalog without re-supplying every image.

Template Settings

These settings live under the Product Images fieldset on the template form.

Time and Size Limits Apply Within a Row, Not Just Between Rows

Every import run has an overall time and download-size budget, shared across every image it downloads. This budget is checked between each image, not just between each row — so a single row that lists many remote images (see Additional Images Separator above) can't quietly use up the whole run's budget on its own before the next row even starts. If the budget runs out mid-row, the remaining images in that row are refused and the row is logged accordingly; already-placed images from earlier in the run are kept.

What Happens to Replaced Images

When When Product Images Exist is set to Overwrite, the old image files are kept on disk — they are never deleted, so nothing is lost by accident. Over time this can leave unused files behind; periodically review your Media Manager and remove any images you no longer need.

Security Notes

• Only image files are accepted. JPG, PNG, GIF, and WebP files are allowed. Anything else — including SVG files — is rejected, even if the file extension is disguised.
• Downloading from URLs is restricted to Super Users. Any other administrator who saves a template with Download from URLs turned on will have it automatically reset to Files on this site.
• Downloads never reach your internal network. The app only fetches from public internet addresses — it refuses local, private, and internal network addresses, so a malicious URL in a CSV file cannot be used to probe your server or network.
• Validate Only performs a true dry run. Running a Product Images template with Run Preview checks the file, the product matches, and every image reference without downloading, writing, or changing anything.
• Downloaded image URLs are redacted in the import log. If a remote image address includes a query string — for example a signed download token some suppliers attach to their URLs — that part is replaced with ?[redacted] wherever the value appears in the Logs tab. The address itself (scheme, host, and path) still shows, so you can tell which image a row referred to.

Typical Workflow

1. Import your catalog first using a Product template — this creates the products.
2. Prepare a second file with the same SKU or product ID column, plus your image columns (main_image, main_image_alt, additional_images, additional_images_alt).
3. Create a Product Images template, map those columns, and set your Image Source and folder settings.
4. Run Run Preview to confirm the report looks correct.
5. Run Run Live Import to attach the photos.

Unreferenced Images Report

Over time, an Overwrite run on a Product Images template can leave old image files on disk that no product uses any more (see What Happens to Replaced Images above). The Unreferenced Images report finds those files for you.

Where to Open It

On the Dashboard tab, open the Templates button in the toolbar and choose Unreferenced Images.

What It Lists

The report scans every Image Folder configured on your Product Images templates — including their thumbs and tiny subfolders — for image files that no product's image record references. It shows each file's path, size, and last-modified date, and you can search or sort the results.

It's Read-Only

There is no delete action on this screen, and running it never deletes, moves, or changes anything. The EDI Orders app never deletes image files during a normal import either — an Overwrite run keeps the old files on disk rather than removing them — so this report exists purely to help you find files worth reviewing yourself in the Media Manager.

Who Can See It

This report is available to administrators who hold both the Edit Products permission and Access Administration Interface on the J2Commerce component — a stricter bar than the plain Edit Products permission every other Product Images screen uses, since this report reads across every configured Image Folder rather than acting on one already-identified product.

Scan Limit

The scan stops after 20,000 files across all folders combined. If your store has more image files than that, the report tells you the scan was capped — run it again after clearing some files, or narrow your templates' Image Folders.

Running a Template

1. Open the template from the Templates tab.
2. Click Run Preview to check the file without changing anything, or Run Live Import to write the changes.
3. Review the results on the Logs tab — every row is recorded as imported, skipped, or failed, with a reason.

Deleting a log. Deleting an import log — on its own or as part of a bulk delete — requires the same permission the log's import type itself required to run. For example, deleting a log from an Order Status or Order Shipment import requires the Edit Orders permission on J2Commerce; deleting a log from a Customer or Customer Address import requires the Configure permission on the Users component, the same permission that import needed to create the accounts in the first place. This keeps a log's row-by-row detail (which can include customer or order data from the original file) visible only to administrators who could act on that data in the first place.

Scheduled Imports

Import templates set to run on a schedule are covered under Import Options -> Trigger Mode when creating a template, and need a one-time Joomla scheduled task — set this up from System -> Scheduled Tasks -> New and choose EDI: Run Imports.

A large file can take longer to import than a single scheduled run allows. The Rows Per Scheduled Run setting, under the template's Scheduled Runs fieldset, caps how many rows one scheduled run processes before it stops and picks up where it left off on the next run. You can also click Resume on an incomplete run's entry in the Logs tab to continue it immediately, without waiting for the next scheduled tick.

• Resume can't overlap a scheduled run for the same file. If you click Resume at the same moment a scheduled run is already processing that file, the app safely skips one of the two rather than letting both write at once — try Resume again in a moment.
• A missing uploaded file closes out its run instead of blocking future imports. If the file behind an incomplete scheduled run has been removed (moved, cleared from the processed-files folder, and so on) before the run could finish, the app can no longer resume it. Rather than leaving that run stuck and blocking every later scheduled import for the same template, it closes the run out as failed and lets your schedule continue normally from the next file.

Troubleshooting

A Product Images row is skipped as "ambiguous"

Cause: The SKU or product ID in that row matches more than one product image record, or more than one product, in your store.

Solution: Open the affected products in J2Commerce -> Catalog -> Products and confirm the SKU is unique, or switch Match Products By to Product ID if your file includes it.

Product images don't appear in the product form's image gallery

Cause: The gallery only lists folders configured under Image Directories in J2Commerce's Image Upload options. The imported images are still saved and shown on the product page and storefront.

Solution: Go to J2Commerce -> Options -> Image Upload and add your template's Image Folder to Image Directories.

"Only Super Users can turn on image downloading" warning

Cause: An administrator without Super User access tried to save a Product Images template with Image Source set to Download from URLs or Both.

Solution: Have a Super User configure the template, or use Files on this site and place the images on the server yourself (for example via FTP) before importing.

An image is refused during import

Cause: The file is not one of the accepted types (JPG, PNG, GIF, WebP), is larger than Maximum Image Size (MB), or the source path/URL could not be reached.

Solution: Check the row's reason in the Logs tab, fix the file or the file reference in your CSV, and re-run the template.