---
title: "EDI Import Export"
description: "Import CSV and EDI data into J2Commerce — orders, stock, pricing, customers, products, and now product images — using the EDI Orders app's import templates."
url: "https://docs.j2commerce.com/v6/apps-and-extensions/apps/app-edi-import"
markdown_url: "https://docs.j2commerce.com/v6/apps-and-extensions/apps/app-edi-import.md"
last_updated: "2026-10-25T19:15:44+00:00"
version: "J2Commerce 6"
breadcrumbs:
  - title: "Home"
    url: "https://docs.j2commerce.com/"
  - title: "J2Commerce 6"
    url: "https://docs.j2commerce.com/v6"
  - title: "Apps and Extensions"
    url: "https://docs.j2commerce.com/v6/apps-and-extensions"
  - title: "Apps"
    url: "https://docs.j2commerce.com/v6/apps-and-extensions/apps"
  - title: "EDI Import Export"
    url: "https://docs.j2commerce.com/v6/apps-and-extensions/apps/app-edi-import"
---

# 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](https://www.j2commerce.com/extensions). It is not included with the core J2Commerce 6 component.

1. Visit [www.j2commerce.com](https://www.j2commerce.com/extensions) 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](https://docs.j2commerce.com/v6/apps-and-extensions/apps/app-edi-import#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.

> **Test with Run Preview first:** Every template can be run in two ways: **Run Preview** checks the whole file and reports what would happen without changing anything in your store. **Run Live Import** writes the changes for real. Always run a preview first, especially the first time you use a new 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.

| Import Entity | What it does |
| --- | --- |
| **Order Status Update** | Updates the status of existing orders (for example, from *Processing* to *Shipped*). |
| **Order Shipment** | Attaches tracking numbers and carrier details to existing orders, and can move the order to a chosen status. |
| **Product Stock Level** | Updates stock quantities on existing products, and can also flip a product's in-stock/out-of-stock status. |
| **Product Price** | Updates pricing on existing products. |
| **Category** | Creates or updates product categories. |
| **Manufacturer** | Creates or updates manufacturers/brands. |
| **Customer** | Creates or updates customer accounts. |
| **Customer Address** | Creates or updates addresses on existing customer accounts. |
| **Product** | Creates new products or updates existing ones, matched by SKU or product ID. |
| **Product Variant** | Updates existing product variants (SKU-level records) by their own SKU, optionally narrowed to one parent product. See [Product Variant](https://docs.j2commerce.com/v6/apps-and-extensions/apps/app-edi-import#product-variant) below. |
| **Product Images** | Attaches a main image and additional images to a product that **already exists**, matched by SKU or product ID. See [Product Images](https://docs.j2commerce.com/v6/apps-and-extensions/apps/app-edi-import#product-images) below. |
| **Custom (Any Table/Column)** | An advanced mode for mapping CSV columns to any table and column your import doesn't fit a dedicated entity for. |

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:

| Setting | Description | Default |
| --- | --- | --- |
| **Match Products By** | The column that identifies a product already in your store. **Product ID** matches the J2Commerce product ID. **SKU** matches the SKU of the product's main variant. If a SKU matches more than one product, the row is skipped — the app never guesses. | SKU |
| **Overwrite Existing Product IDs** | *Product and Product Variant only.* When **No**, a row that matches an existing product is skipped. When **Yes**, matching rows update the existing product. | No |
| **When a Product Already Exists** | *Product and Product Variant only.* **Fill missing fields** only writes into empty fields. **Overwrite** replaces existing values with the file's values. | Fill missing fields |

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:

| Column | Description |
| --- | --- |
| `main_image` | Path or URL to the product's main image. |
| `main_image_alt` | Alt text for the main image. If left blank, the app uses the product's own title. |
| `additional_images` | One or more additional image paths/URLs. |
| `additional_images_alt` | Alt text for each additional image, in the same order. |

**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.

| Setting | Description | Default |
| --- | --- | --- |
| **Image Source** | Where the image values in your file point. **Files on this site** reads paths relative to the site root. **Download from URLs** fetches `http` and `https` addresses. **Both (detect per value)** accepts either, per row. Only Super Users can turn on downloading. | Files on this site |
| **Local Image Folder** | Local image paths must resolve inside this folder (and it must itself be inside your `images` folder). | `images` |
| **Image Folder** | The folder imported images are saved to, inside your `images` folder — never your original files. Thumbnail and tiny images are created automatically in its `thumbs` and `tiny` subfolders. To browse imported images in the product form's image gallery, add this folder to **Image Directories** under J2Commerce's Image Upload options. | `images/com_j2commerce/products` |
| **Process Images** | When **Yes**, images are resized, converted to WebP, and thumbnail/tiny versions are generated automatically, using the same Image Upload settings as **J2Commerce** -> **Options** -> **Image Upload**. | Yes |
| **When Product Images Exist** | **Fill missing fields** only adds images to products that don't have any yet — the safest choice. **Append** adds the file's additional images after the ones the product already has. **Overwrite** replaces the images entirely. | Fill missing fields |
| **Additional Images Separator** | The character used to list more than one additional image in a single CSV cell. | `\|` (pipe) |
| **Maximum Image Size (MB)** | The largest image file the app will accept. | 10 |
| **Download Timeout (seconds)** | How long to wait for a remote image to download before giving up. Only shown when Image Source allows downloads. | 15 |
| **Allow Multi-Row Products** | Turn this on for exports (like Shopify's) that list one product per row, followed by extra rows that carry only more images with no SKU or product ID repeated. With this on, a row with an empty SKU/product ID attaches its images to the product named on the row directly above it. Leave it off when every row names its own product — rows with an empty SKU/product ID are then skipped. | No |

> **Allow Multi-Row Products survives a paused scheduled run:** When a scheduled run stops partway through a large file and picks up again on its next tick (see [Scheduled Imports](https://docs.j2commerce.com/v6/apps-and-extensions/apps/app-edi-import#scheduled-imports) below), the app remembers which product the last processed row belonged to. A chain of image-only rows is never broken just because a run happened to pause between them.

### 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](https://docs.j2commerce.com/v6/apps-and-extensions/apps/app-edi-import#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.

> **Run Live Import cannot be undone from this dialog:** **Run Live Import** writes directly to your database. Always run **Run Preview** first and review the results before running the live import.

**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.