Imports & Exports - Spree Commerce documentation

Overview

Spreadsheets remain how most merchants think about bulk work. A supplier sends a price list as CSV; the finance team wants last quarter’s orders in Excel; a migration from another platform arrives as one enormous product export. Spree handles both directions as background work, so a hundred-thousand-row file doesn’t tie up a browser tab or time out.

What can be imported and exported

Data	Import	Export
Products	Yes	Yes
Product translations	Yes	Yes
Customers	Yes	Yes
Orders	—	Yes
Gift cards	—	Yes
Coupon codes	—	Yes
Newsletter subscribers	—	Yes

Orders are export-only on purpose. An order is a financial record of something that happened; inventing them from a spreadsheet would let the books say something that never occurred.

Exporting

An export is created, runs in the background, and produces a file to download.

const exportJob = await adminClient.exports.create({
  type: 'products',
})

// Poll until it's done
const status = await adminClient.exports.get(exportJob.id)
status.done         // true once the file is ready
status.download_url // available once done

spree api post /exports -d '{"type": "products"}'
spree api get /exports

Exporting a filtered set

An export can carry the same filters as the listing it came from, so “export what I’m looking at” does what a merchant expects — this quarter’s orders, this brand’s products, not the entire table.

await adminClient.exports.create({
  type: 'orders',
  search_params: { completed_at_gteq: '2026-01-01' },
})

curl -X POST 'https://api.mystore.com/api/v3/admin/exports' \
  -H 'X-Spree-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "orders", "search_params": { "completed_at_gteq": "2026-01-01" } }'

In the dashboard this is the Export button on any list — whatever filters are applied come along.

Importing

Importing has an extra step, because a file from somewhere else won’t have Spree’s column names. You upload it, say which of your columns means what, and then it runs.

Upload the file

Admin SDK

const importJob = await adminClient.imports.create({
  type: 'products',
  file: uploadedFileId,
})

Spree reads the header row and tells you which columns it found.

Match columns to fields

Admin SDK

await adminClient.imports.completeMapping(importJob.id, {
  mappings: [
    { schema_field: 'name', file_column: 'Product Title' },
    { schema_field: 'sku', file_column: 'Item Code' },
    { schema_field: 'price', file_column: 'RRP' },
  ],
})

Obvious matches are suggested for you; you only correct the ones that differ.

Watch it run

Admin SDK

const status = await adminClient.imports.get(importJob.id)

status.status         // "processing" → "completed"
status.rows_count     // total
status.completed_rows_count
status.failed_rows_count

Download a template for any import type to see the expected columns — the quickest way to prepare a file that maps cleanly.

When rows fail

Some rows will fail. A price with a currency symbol in it, a required field left blank, a duplicate SKU. A failed row doesn’t stop the import. The good rows are imported; the bad ones are set aside with the reason.

const { data: failures } = await adminClient.imports.rows.list(importJob.id, {
  status_eq: 'failed',
})

failures.forEach((row) => {
  row.row_number        // 47
  row.validation_errors // "Price is not a number"
})

// After fixing the source data
await adminClient.imports.retryFailedRows(importJob.id)

curl 'https://api.mystore.com/api/v3/admin/imports/imp_xxx/rows?q[status_eq]=failed' \
  -H 'X-Spree-API-Key: sk_xxx'

Retrying re-runs only the failures, so a file where three rows out of ten thousand were wrong doesn’t need re-importing whole.

A value that isn’t a number is rejected, never guessed at. A price written as "12,50" fails rather than being read as 1250 — which would be a hundredfold overcharge. Fix the file rather than hoping the import is lenient.

Interrupted work resumes

Imports remember which row they reached. If the server restarts halfway through a large file, processing picks up where it stopped rather than starting again or skipping the remainder.

Products with several variants

A product with variants spans several rows — one per variant, repeating the product columns. Rows are grouped by the product identifier, so a t-shirt in three sizes is three rows and becomes one product. Custom fields can be imported too: a column matching a custom field you’ve defined maps to it like any built-in field.

Knowing when it’s finished

Imports and exports emit events as they progress, which also reach webhooks. That’s how you trigger the next step of a pipeline — notify a channel, kick off a reindex — without polling.

Event	When
`import.created`	An import has been uploaded
`import.progress`	A batch of rows has been processed
`import.completed`	Every row has been attempted
`export.created`	An export has been requested (generation starts in the background)

There is no event when an export’s file is ready — poll the export until done is true.

Permissions

Import and export are gated by the same permissions as the data they touch. Someone who can’t see customers can’t export them — otherwise export would be a way around the whole permission system.

Products — the most-imported data
Custom Fields — importing your own fields
Events — reacting to completion
Staff & Roles — who may import and export

​Overview

​What can be imported and exported

​Exporting

​Exporting a filtered set

​Importing

​When rows fail

​Interrupted work resumes

​Products with several variants

​Knowing when it’s finished

​Permissions

​Related

Overview

What can be imported and exported

Exporting

Exporting a filtered set

Importing

When rows fail

Interrupted work resumes

Products with several variants

Knowing when it’s finished

Permissions

Related