Product Import & Export
Version3.6.12
Compatibility^3.6.0
Categoryimport-export
Downloads1.2K monthly
Last updatedOct 15, 2026
name: product-import-export-plugin title: Product Import & Export description: Vendure plugin for importing and exporting product data via CSV. version: 3.6.4 tags:
- vendure
- plugin
- import
- export
- products
- csv
- bulk
A Vendure plugin for importing and exporting product data via CSV. Supports bulk product management and data migration between environments.
Features
- Import – Bulk upload products from CSV with validation, custom fields, assets, facets, and variants
- Export – Export products to CSV with selected fields; export all products or a selection
- Storage strategies – Store exported files in S3 or locally on disk (with automatic fallback)
- UI – Admin UI and Dashboard integration for import and export
Compatibility
Vendure ^3.6.0
Getting started
Configuration
Add the plugin to your Vendure configuration.
Typescript
Configuration Options
Import options
| Option | Type | Default | Description |
|---|---|---|---|
updateProductSlug | boolean | true | Update product slug from the name field in the CSV |
restoreSoftDeleted | boolean | true | Restore soft-deleted products/variants found by id or SKU during import. If false, new products will be created instead. |
storageStrategy | ImportJobStorageStrategy | local disk | Strategy instance for queued import file storage and retrieval. |
storageStrategyFactory | (injector: Injector) => ImportJobStorageStrategy | undefined | Factory for DI-aware strategy creation (recommended for S3/remote storage). |
importJobStorage | 'local' | 's3' | 'local' | Deprecated compatibility flag. Prefer storageStrategy / storageStrategyFactory. |
Available import storage strategies:
LocalImportJobStorageStrategy(default)S3ImportJobStorageStrategy
Export options
| Option | Type | Default | Description |
|---|---|---|---|
defaultFileName | string | 'products_export.csv' | Default filename for exports |
exportAssetsAsOptions | ('url' | 'json')[] | ['url', 'json'] | Available formats for asset export |
defaultExportAssetsAs | 'url' | 'json' | 'url' | Default asset export format |
defaultExportFields | string[] | See above | Fields that will be pre-selected in the export UI |
requiredExportFields | string[] | ['name', 'sku'] | Fields that must always be included |
customExportColumns | CustomExportColumn[] | undefined | Extra CSV columns resolved per variant row. See Custom export columns below. |
storageStrategy | 's3' | 'disk' | 'disk' | Where exported files are stored |
s3Options | object | undefined | S3 configuration (required when storageStrategy is 's3') |
Storage strategy
The plugin supports configurable storage for exported files:
- S3 – Stores export files in an S3-compatible bucket
- Disk (default) – Saves files locally on the server
Custom export columns
Add columns to the exported CSV whose value is computed per variant row, for example a permalink built from the product slug and variant SKU.
Typescript
name– Must be non-empty, must not contain:(colon-suffixed headers are reserved for translated columns), must not collide with a built-in export field name, and must be unique amongcustomExportColumnsentries. These rules are validated when the plugin is initialised, so a misconfigured column fails fast at startup rather than mid-export.onExportStart– Optional. Awaited once per export job, before the firstresolvecall.resolve(ctx, injector, product, variant)– Called once per exported variant row. Its return value is written to the cell (String(value), or an empty cell fornull/undefined). Useinjectorto pull in Vendure services via DI.- A custom column only appears in the export when its
nameis included in the selected export fields, both in the header row and in the request; otherwise it is skipped entirely. - Fail-soft – If
resolvethrows, the plugin logs a warning and writes an empty cell for that row instead of failing the whole export.
CSV Format for Import
Required columns
name– Product name (usename:en,name:svetc. for multiple languages)sku– Variant SKU (unique per variant)
Optional columns
| Column | Format | Example |
|---|---|---|
name, slug, description | Text, or name:en, name:sv for translations | My Product |
assets | Pipe-separated URLs, or JSON [{"url":"...","name":"..."}] | https://example.com/1.jpg|https://example.com/2.jpg |
facets | facet:value pairs, pipe-separated | Brand:Acme|Category:Electronics |
optionGroups | Pipe-separated group names. Use name:code to share a group across products (see Sharing option groups) | Size|Color or size:shoe-size |
optionValues | Pipe-separated values (order matches option groups) | Large|Blue |
price | Number (in smallest currency unit) | 9999 |
taxCategory | Tax category name | standard |
stockOnHand | Number | 100 |
trackInventory | true or false | true |
variantAssets | Same format as assets | https://example.com/variant.jpg |
variantFacets | Same format as facets | Material:Cotton |
enabled | true or false | true |
| Custom fields | Column name = custom field name; value depends on field type | Add columns for any Product or ProductVariant custom fields defined in your Vendure config. Relation custom fields export the related entity's id (id|id for list fields), including fields that relate a product or variant to its own entity type. |
Import behavior rules
- If a column is omitted from the CSV header, that field is left unchanged on existing products/variants.
- If a column exists in the header but the cell is empty, that field is explicitly cleared.
- For products with more than one variant,
optionGroupsandoptionValuesare required. - The header is checked before the upload is queued. A custom field column the shop does not have, a missing required column or mixed translated and untranslated columns make the upload answer
400with{ "errors": ["Invalid custom field: product:clubName"] }, the Dashboard lists the errors, and nothing is imported. - Product data (
slug,description,assets,facets,optionGroupsandproduct:custom fields) is read from a product's first row, the row with aname. If a later variant row of the product fills one of these columns, that product is not imported and the import reports the column and line. Other products in the file still import.idmay repeat on every row.
Relations to variants by SKU
A relation custom field to ProductVariant can name the related variant by SKU instead of id. Add :sku to the column header after the type:
Csv
- Each SKU must match exactly one variant that is not deleted, in any channel. A list field takes
SKU|SKU. - The upload is checked before it is queued. If a SKU matches no variant or more than one, the upload answers
400with{ "errors": ["Row 2: no variant with SKU BASE-TEE-M"] }, the Dashboard lists the rows, and nothing is imported. The import job checks again when it runs. - The related variants must exist before the upload, so import them in an earlier file.
:skuis the only lookup, and it works only on relation fields toProductVariant. Columns without it still take ids.
Sharing option groups
By default, each product gets its own option groups. To share an option group across
multiple products (e.g. a common "Size" group for all shoes), use the name:code syntax in the
optionGroups column: size:shoe-size. All products that reference the same code will share
a single option group. Products using a plain name (e.g. just size) will each get their own
independent option group.
Csv
The first product to reference a given code defines the full set of option values for that
shared group; subsequent products may use any subset of those values. Codes are language-
agnostic — only the name portion before the colon is translated per language column
(optionGroups:en, optionGroups:sv, etc.).
Multi-language support
Use language-specific columns by suffixing the field name with the language code. The language codes must match those configured in your Vendure instance (e.g. en, sv).
| Column pattern | Example columns | Use case |
|---|---|---|
name:en, name:sv | Product name per lang | Translated product names |
slug:en, slug:sv | Slug per lang | Translated URLs |
description:en | Description per lang | Translated descriptions |
facets:en, facets:sv | Facets per lang | Translated facet names and values |
optionGroups:en | Option groups per lang | Translated option group names (e.g. Size, Color) |
optionValues:en | Option values per lang | Translated option values (e.g. Large, Blue) |
Example CSV with English and Swedish:
Csv
Multiple values (pipe separator)
Fields that can have multiple values use the pipe character | as a separator:
- Facets:
Brand:Acme|Category:Electronics - Option groups:
Size|Color - Option values:
Large|Blue(order matches option groups) - Assets:
https://example.com/1.jpg|https://example.com/2.jpg
Usage
:::note The Admin UI offers basic import and export. Some features such as the export-all option and the list of exported files are only available in the Dashboard. New features will be added to the Dashboard only. :::
Importing products
- Create a CSV with the columns above.
- Go to the Admin UI or Dashboard and open the Product Import section.
- Upload the CSV and choose options (update slugs, restore soft-deleted, main language).
- Select the update strategy: merge (keep existing facets/assets) or replace (overwrite).
- Start the import.
Exporting products
- In the Admin UI or Dashboard, select products to export (or use bulk export).
- Configure export fields (assets, facets, custom fields, etc.).
- For products with more than one variant,
optionGroupsandoptionValuesmust be included. id(the Vendure product id) is available as a selectable export field. It is written after the translatedname/slug/descriptioncolumns, so it is never CSV column 0, since import treats column 0 positionally as a product id for by-id matching.- If
customExportColumnsis configured, only the columns whosenameis selected are written to the CSV. - The job reports progress per page; the Dashboard job queue shows it.
productIdis not available as a selectable export field.- If
customFieldsare not selected, no custom-field columns are written to the CSV. - Product custom-field columns come after the other product columns (
namethroughfacets) and beforeoptionGroups, which is the last product column so it sits next tooptionValues, the first variant column. Product custom fields are filled on a product's first row only. Import reads product data from that row, so edit product fields there.
- For products with more than one variant,
- Choose asset format: URL or JSON.
- Start the export (it is added to a job queue and runs in the background).
- Download the CSV when the export is complete. Your downloaded files will be listed in the export view.
Optional: Email notification on export complete
If you use @vendure/email-plugin, you can add an email notification when an export finishes from the /email subpath.
The plugin now provides a default fallback template for product-export-complete/body.hbs.
If you define your own template in your app's template directory, your template takes precedence.
Note: templates for @vendure/email-plugin should be valid MJML.
Typescript
Resources
Changelog
3.6.12
🩹 Fixes
- product-import-export-plugin: write an imported variant and its prices in one transaction (#55)
3.6.11
🩹 Fixes
- product-import-export-plugin: reject an upload with an unknown column before it is queued (#54)
3.6.10
🩹 Fixes
- product-import-export-plugin: read SKU relation columns once per import (#53)
- product-import-export-plugin: list rejected upload rows in the Admin UI (#52)
3.6.9
🩹 Fixes
- product-import-export-plugin: give a shared option group every value the file uses (#50)
3.6.8
🩹 Fixes
- product-import-export-plugin: store import job progress as a whole number (#49)
3.6.7
🚀 Features
- product-import-export-plugin: link ProductVariant relation fields by SKU on import (#48)
3.6.6
🩹 Fixes
- product-import-export-plugin: put optionGroups last among the product columns, next to optionValues (#40)
- product-import-export-plugin: reference @types/multer in lowercase so the build works on Linux (#39)
3.6.5
🩹 Fixes
- product-import-export-plugin: keep product data on a product's first row (#34)
3.6.4
🚀 Features
🩹 Fixes
- product-import-export-plugin: export self-referencing relation custom fields without a duplicate table alias (#31, #22, #23, #26)
3.6.3
🩹 Fixes
- product-import-export-plugin: secure REST API, stop leaking storage credentials (#24)
3.6.2
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.6.1
🚀 Features
- add custom changelog renderer to filter out prerelease versions (4412746)
3.6.0
🚀 Features
- product-import-export-plugin: integrate active channel management into export and import components (1d3eef1)
- product-import-export-plugin: add installation ID and enhance e2e database management (78eeffb)
- product-import-export-plugin: add popover help for export asset options (7aa8373)
- product-import-export-plugin: implement export configuration panel and enhance export dialog (d2e1f34)
- product-import-export-plugin: enhance product export functionality and update tests (de56d44)
- product-import-export-plugin: update dependencies and enhance import/export functionality (9c78665)
- product-import-export-plugin: enhance email notification and import/export functionality (c133dc5)
- product-import-export-plugin: enforce import/export acceptance criteria and enhance documentation (b1a93b6)
- product-import-export-plugin: update pre-version command and clean up export artifacts (1cde024)
- product-import-export-plugin: optimize asset handling and caching in product importer (9d2888e)
- product-import-export-plugin: enhance testing and export functionality (1764eb2)
- enhance file name validation for product export functionality (f9d5a45)
- enhance export storage strategy configuration (d589906)
- abstract logic into separate strategies (1c7d0c7)
- enhance product export functionality with file name sanitization and S3 region update (06af120)
- add S3 storage support for product export functionality (08c0901)
🩹 Fixes
- plugins: correct Vendure compatibility and add hub-required JSDoc (ae089bd)
- product-import-export-plugin: poll exports list and restore featured asset on import (644099a)
- product-import-export-plugin: update dashboard and export settings screenshots (2129b39)
- correct file path handling and ensure consistent file name sanitization in product export (03a5bb5)
3.3.1
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.2.1
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.2.0
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.1.10
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.1.9
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.1.8
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.1.7
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.1.6
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.1.5
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.1.4
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.1.3
🚀 Features
- enhance product import logic to handle soft-deleted products (c88a164)
3.1.2
🩹 Fixes
- correct languageCode reference in slug assignment logic (6c4d56d)
3.1.1
🩹 Fixes
- update slug assignment logic in ProductImporter (#74)
3.1.0
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.0.31-0
🩹 Fixes
- improve error handling and type safety in import/export plugin (81ca5cf)
3.0.30
🚀 Features
- product-import-export-plugin: enhance product export functionality with temporary file handling (aed754f)
3.0.29
🚀 Features
- product-import-export-plugin: add bulk export and exported files list components (eb56ade)
3.0.29-1
🚀 Features
- product-import-export-plugin: implement product export queue and enhance export functionality (7e2d9f0)
3.0.29-0
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.0.28-0
🚀 Features
- product-import-export-plugin: replace request header logic with channel-specific headers (dfc781c)
- product-import-export-plugin: enhance import/export functionality and dashboard integration (825ee89)
3.0.27-4
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.0.27-3
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.0.27-2
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.0.27-1
This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes.
3.0.27-0
🚀 Features
- product-import-export-plugin: add restoreSoftDeleted option for product import (0458a2a)
- product-importer: enhance product variant handling (4af2198)
- product-import-export-plugin: enhance product import service with event bus integration and collection filtering (#48)
- product-import-export-plugin: implement removal of option groups from product (39f34ec)
- Enhance asset importer with URL and local file stream handling (2b5ae3d)
🩹 Fixes
- product-import-export-plugin: improve import parser handling (c952c7b)
- product-import-export-plugin: improve variant enabled handling (a3a6af3)
- product-import-export-plugin: improve option group handling and validate custom fields (a95db85)
- product-import-export-plugin: handle undefined prices in product variants (#49)
- Refactor facetValues and options mapping for consistency in extended fast importer (3514892)
- Improve asset and product importer logic for better channel handling and data consistency (bc9416e)
- Assign assets to current channel on import (#41)
3.0.24-0
🚀 Features
- product-import-export-plugin: add restoreSoftDeleted option for product import (0458a2a)
- product-importer: enhance product variant handling (4af2198)
- product-import-export-plugin: enhance product import service with event bus integration and collection filtering (#48)
- product-import-export-plugin: implement removal of option groups from product (39f34ec)
- Enhance asset importer with URL and local file stream handling (2b5ae3d)
🩹 Fixes
- product-import-export-plugin: improve import parser handling (c952c7b)
- product-import-export-plugin: improve variant enabled handling (a3a6af3)
- product-import-export-plugin: improve option group handling and validate custom fields (a95db85)
- product-import-export-plugin: handle undefined prices in product variants (#49)
- Refactor facetValues and options mapping for consistency in extended fast importer (3514892)
- Improve asset and product importer logic for better channel handling and data consistency (bc9416e)
- Assign assets to current channel on import (#41)
3.0.23-0
🚀 Features
- product-import-export-plugin: add restoreSoftDeleted option for product import (0458a2a)
- product-importer: enhance product variant handling (4af2198)
- product-import-export-plugin: enhance product import service with event bus integration and collection filtering (#48)
- product-import-export-plugin: implement removal of option groups from product (39f34ec)
- Enhance asset importer with URL and local file stream handling (2b5ae3d)
🩹 Fixes
- product-import-export-plugin: improve import parser handling (c952c7b)
- product-import-export-plugin: improve variant enabled handling (a3a6af3)
- product-import-export-plugin: improve option group handling and validate custom fields (a95db85)
- product-import-export-plugin: handle undefined prices in product variants (#49)
- Refactor facetValues and options mapping for consistency in extended fast importer (3514892)
- Improve asset and product importer logic for better channel handling and data consistency (bc9416e)
- Assign assets to current channel on import (#41)
3.0.22
🩹 Fixes
- product-import-export-plugin: improve import parser handling (c952c7b)
3.0.21
🚀 Features
- product-importer: enhance product variant handling (4af2198)
- product-import-export-plugin: enhance product import service with event bus integration and collection filtering (#48)
- product-import-export-plugin: implement removal of option groups from product (39f34ec)
- Enhance asset importer with URL and local file stream handling (2b5ae3d)
🩹 Fixes
- product-import-export-plugin: improve variant enabled handling (a3a6af3)
- product-import-export-plugin: improve option group handling and validate custom fields (a95db85)
- product-import-export-plugin: handle undefined prices in product variants (#49)
- Refactor facetValues and options mapping for consistency in extended fast importer (3514892)
- Improve asset and product importer logic for better channel handling and data consistency (bc9416e)
- Assign assets to current channel on import (#41)