Create an import

Queues a CSV import. Upload the file first via POST /api/v3/admin/direct_uploads and pass the returned signed_id as attachment. On success the import is in the mapping state and the response carries the mapping payload: schema_fields (the canonical columns for the type), csv_headers, a sample_row, and the auto-assigned mappings.

Adjust mappings if needed, then call PATCH /admin/imports/{id}/complete_mapping to start processing. Poll GET /admin/imports/{id} while status is completed_mapping/processing; terminal statuses are completed and failed.

Required scope: the write scope of the imported resource — write_products for product imports, write_customers for customer imports, etc. (for API-key authentication).

POST

api

admin

imports

Create an import

const options = {
  method: 'POST',
  headers: {
    'x-spree-api-key': '<api-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'Spree::Imports::Products',
    attachment: 'eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed',
    preferred_delimiter: ',',
    results_url: 'https://admin.example.com/store_abc/settings/imports'
  })
};

fetch('http://{defaultHost}/api/v3/admin/imports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url http://{defaultHost}/api/v3/admin/imports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-spree-api-key: <api-key>' \
  --data '
{
  "type": "Spree::Imports::Products",
  "attachment": "eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed",
  "preferred_delimiter": ",",
  "results_url": "https://admin.example.com/store_abc/settings/imports"
}
'

{
  "id": "imp_gbHJdmfrXB",
  "number": "IM260124970",
  "type": "Spree::Imports::Products",
  "rows_count": 0,
  "created_at": "2026-07-24T18:11:02.989Z",
  "updated_at": "2026-07-24T18:11:03.122Z",
  "status": "mapping",
  "owner_type": "Spree::Store",
  "owner_id": "store_UkLWZg9DAJ",
  "user_id": "admin_UkLWZg9DAJ",
  "processing_errors": null,
  "preferred_delimiter": ",",
  "original_filename": "import.csv",
  "original_byte_size": 44,
  "original_file_url": "/api/v3/admin/imports/imp_gbHJdmfrXB/download",
  "completed_rows_count": 0,
  "failed_rows_count": 0,
  "schema_fields": [
    {
      "name": "slug",
      "label": "Slug",
      "required": true
    },
    {
      "name": "sku",
      "label": "SKU",
      "required": true
    },
    {
      "name": "name",
      "label": "Name",
      "required": true
    },
    {
      "name": "price",
      "label": "Price",
      "required": true
    },
    {
      "name": "status",
      "label": "Status",
      "required": false
    },
    {
      "name": "description",
      "label": "Description",
      "required": false
    },
    {
      "name": "meta_title",
      "label": "Meta Title",
      "required": false
    },
    {
      "name": "meta_description",
      "label": "Meta Description",
      "required": false
    },
    {
      "name": "meta_keywords",
      "label": "Meta Keywords",
      "required": false
    },
    {
      "name": "tags",
      "label": "Tags",
      "required": false
    },
    {
      "name": "compare_at_price",
      "label": "Compare at Price",
      "required": false
    },
    {
      "name": "currency",
      "label": "Currency",
      "required": false
    },
    {
      "name": "width",
      "label": "Width",
      "required": false
    },
    {
      "name": "height",
      "label": "Height",
      "required": false
    },
    {
      "name": "depth",
      "label": "Depth",
      "required": false
    },
    {
      "name": "dimensions_unit",
      "label": "Dimensions Unit",
      "required": false
    },
    {
      "name": "weight",
      "label": "Weight",
      "required": false
    },
    {
      "name": "weight_unit",
      "label": "Weight Unit",
      "required": false
    },
    {
      "name": "available_on",
      "label": "Available On",
      "required": false
    },
    {
      "name": "discontinue_on",
      "label": "Discontinue On",
      "required": false
    },
    {
      "name": "track_inventory",
      "label": "Track Inventory",
      "required": false
    },
    {
      "name": "inventory_count",
      "label": "Inventory Count",
      "required": false
    },
    {
      "name": "inventory_backorderable",
      "label": "Inventory Backorderable",
      "required": false
    },
    {
      "name": "tax_category",
      "label": "Tax Category",
      "required": false
    },
    {
      "name": "shipping_category",
      "label": "Shipping Category",
      "required": false
    },
    {
      "name": "image1_src",
      "label": "Image 1 URL",
      "required": false
    },
    {
      "name": "image2_src",
      "label": "Image 2 URL",
      "required": false
    },
    {
      "name": "image3_src",
      "label": "Image 3 URL",
      "required": false
    },
    {
      "name": "option1_name",
      "label": "Option 1 Name",
      "required": false
    },
    {
      "name": "option1_value",
      "label": "Option 1 Value",
      "required": false
    },
    {
      "name": "option2_name",
      "label": "Option 2 Name",
      "required": false
    },
    {
      "name": "option2_value",
      "label": "Option 2 Value",
      "required": false
    },
    {
      "name": "option3_name",
      "label": "Option 3 Name",
      "required": false
    },
    {
      "name": "option3_value",
      "label": "Option 3 Value",
      "required": false
    },
    {
      "name": "category1",
      "label": "Category 1",
      "required": false
    },
    {
      "name": "category2",
      "label": "Category 2",
      "required": false
    },
    {
      "name": "category3",
      "label": "Category 3",
      "required": false
    }
  ],
  "csv_headers": [
    "slug",
    "sku",
    "name",
    "price"
  ],
  "sample_row": {
    "slug": "widget",
    "sku": "W-1",
    "name": "Widget",
    "price": "10.00"
  },
  "mappings": [
    {
      "id": "immap_UkLWZg9DAJ",
      "schema_field": "slug",
      "file_column": "slug",
      "required": true
    },
    {
      "id": "immap_gbHJdmfrXB",
      "schema_field": "sku",
      "file_column": "sku",
      "required": true
    },
    {
      "id": "immap_EfhxLZ9ck8",
      "schema_field": "name",
      "file_column": "name",
      "required": true
    },
    {
      "id": "immap_VqXmZF31wY",
      "schema_field": "price",
      "file_column": "price",
      "required": true
    },
    {
      "id": "immap_uw2YK1rnl0",
      "schema_field": "status",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_OIJLhNcSbf",
      "schema_field": "description",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_AXs1igzRC6",
      "schema_field": "meta_title",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_p6klVeMgbn",
      "schema_field": "meta_description",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_nJqfPa3Cpe",
      "schema_field": "meta_keywords",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_98FqgRua4h",
      "schema_field": "tags",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_xhoCpeNMWu",
      "schema_field": "compare_at_price",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_vEmzDoNU0H",
      "schema_field": "currency",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_2KY5XM6frI",
      "schema_field": "width",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_HOVtlDrOmL",
      "schema_field": "height",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_ed6l8wVqSM",
      "schema_field": "depth",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_s18jaGonyx",
      "schema_field": "dimensions_unit",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_GZUcnUYI5A",
      "schema_field": "weight",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_ROeNhrwyV9",
      "schema_field": "weight_unit",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_L3pHOn63Vw",
      "schema_field": "available_on",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_PQNMcnNFWw",
      "schema_field": "discontinue_on",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_C9SrJgpzQ4",
      "schema_field": "track_inventory",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_YHETxCGlb0",
      "schema_field": "inventory_count",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_5OQZnCRf8J",
      "schema_field": "inventory_backorderable",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_F0GX8NaP3Y",
      "schema_field": "tax_category",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_kOKT9MVfb0",
      "schema_field": "shipping_category",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_3uWpPTcf5W",
      "schema_field": "image1_src",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_D6Psx31WaT",
      "schema_field": "image2_src",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_msx3nOJap6",
      "schema_field": "image3_src",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_5CQZnCRf8J",
      "schema_field": "option1_name",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_M2nyloHRUQ",
      "schema_field": "option1_value",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_prklVeMgbn",
      "schema_field": "option2_name",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_so8jaGonyx",
      "schema_field": "option2_value",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_rsClYtECFI",
      "schema_field": "option3_name",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_8DR0I7fEbw",
      "schema_field": "option3_value",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_aAtNvLSUAr",
      "schema_field": "category1",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_QiA48cIW7A",
      "schema_field": "category2",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_QDA48cIW7A",
      "schema_field": "category3",
      "file_column": null,
      "required": false
    }
  ]
}

{
  "error": {
    "code": "validation_error",
    "message": "Type can't be blank",
    "details": {
      "type": [
        "can't be blank"
      ]
    }
  }
}

Authorizations

x-spree-api-key

string

header

required

Secret API key for admin access

Authorization

string

header

required

JWT token for admin user authentication

Headers

x-spree-api-key

string

required

Authorization

string

required

Body

application/json

type

enum<string>

required

Available options:

Spree::Imports::Products,

Spree::Imports::Customers,

Spree::Imports::ProductTranslations

Example:

"Spree::Imports::Products"

attachment

string

required

ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads.

Example:

"eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed"

preferred_delimiter

enum<string>

CSV column separator. Defaults to a comma.

Available options:

,,

;,

|,

Example:

","

results_url

string

Absolute URL of your admin imports view; the import-done email links back to it with ?import=<id> appended. Only honored when it matches one of the store's configured allowed origins.

Example:

"https://admin.example.com/store_abc/settings/imports"

Response

import created in mapping state

List imports

Download an import template

⌘I

Create an import

const options = {
  method: 'POST',
  headers: {
    'x-spree-api-key': '<api-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'Spree::Imports::Products',
    attachment: 'eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed',
    preferred_delimiter: ',',
    results_url: 'https://admin.example.com/store_abc/settings/imports'
  })
};

fetch('http://{defaultHost}/api/v3/admin/imports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url http://{defaultHost}/api/v3/admin/imports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-spree-api-key: <api-key>' \
  --data '
{
  "type": "Spree::Imports::Products",
  "attachment": "eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed",
  "preferred_delimiter": ",",
  "results_url": "https://admin.example.com/store_abc/settings/imports"
}
'

{
  "id": "imp_gbHJdmfrXB",
  "number": "IM260124970",
  "type": "Spree::Imports::Products",
  "rows_count": 0,
  "created_at": "2026-07-24T18:11:02.989Z",
  "updated_at": "2026-07-24T18:11:03.122Z",
  "status": "mapping",
  "owner_type": "Spree::Store",
  "owner_id": "store_UkLWZg9DAJ",
  "user_id": "admin_UkLWZg9DAJ",
  "processing_errors": null,
  "preferred_delimiter": ",",
  "original_filename": "import.csv",
  "original_byte_size": 44,
  "original_file_url": "/api/v3/admin/imports/imp_gbHJdmfrXB/download",
  "completed_rows_count": 0,
  "failed_rows_count": 0,
  "schema_fields": [
    {
      "name": "slug",
      "label": "Slug",
      "required": true
    },
    {
      "name": "sku",
      "label": "SKU",
      "required": true
    },
    {
      "name": "name",
      "label": "Name",
      "required": true
    },
    {
      "name": "price",
      "label": "Price",
      "required": true
    },
    {
      "name": "status",
      "label": "Status",
      "required": false
    },
    {
      "name": "description",
      "label": "Description",
      "required": false
    },
    {
      "name": "meta_title",
      "label": "Meta Title",
      "required": false
    },
    {
      "name": "meta_description",
      "label": "Meta Description",
      "required": false
    },
    {
      "name": "meta_keywords",
      "label": "Meta Keywords",
      "required": false
    },
    {
      "name": "tags",
      "label": "Tags",
      "required": false
    },
    {
      "name": "compare_at_price",
      "label": "Compare at Price",
      "required": false
    },
    {
      "name": "currency",
      "label": "Currency",
      "required": false
    },
    {
      "name": "width",
      "label": "Width",
      "required": false
    },
    {
      "name": "height",
      "label": "Height",
      "required": false
    },
    {
      "name": "depth",
      "label": "Depth",
      "required": false
    },
    {
      "name": "dimensions_unit",
      "label": "Dimensions Unit",
      "required": false
    },
    {
      "name": "weight",
      "label": "Weight",
      "required": false
    },
    {
      "name": "weight_unit",
      "label": "Weight Unit",
      "required": false
    },
    {
      "name": "available_on",
      "label": "Available On",
      "required": false
    },
    {
      "name": "discontinue_on",
      "label": "Discontinue On",
      "required": false
    },
    {
      "name": "track_inventory",
      "label": "Track Inventory",
      "required": false
    },
    {
      "name": "inventory_count",
      "label": "Inventory Count",
      "required": false
    },
    {
      "name": "inventory_backorderable",
      "label": "Inventory Backorderable",
      "required": false
    },
    {
      "name": "tax_category",
      "label": "Tax Category",
      "required": false
    },
    {
      "name": "shipping_category",
      "label": "Shipping Category",
      "required": false
    },
    {
      "name": "image1_src",
      "label": "Image 1 URL",
      "required": false
    },
    {
      "name": "image2_src",
      "label": "Image 2 URL",
      "required": false
    },
    {
      "name": "image3_src",
      "label": "Image 3 URL",
      "required": false
    },
    {
      "name": "option1_name",
      "label": "Option 1 Name",
      "required": false
    },
    {
      "name": "option1_value",
      "label": "Option 1 Value",
      "required": false
    },
    {
      "name": "option2_name",
      "label": "Option 2 Name",
      "required": false
    },
    {
      "name": "option2_value",
      "label": "Option 2 Value",
      "required": false
    },
    {
      "name": "option3_name",
      "label": "Option 3 Name",
      "required": false
    },
    {
      "name": "option3_value",
      "label": "Option 3 Value",
      "required": false
    },
    {
      "name": "category1",
      "label": "Category 1",
      "required": false
    },
    {
      "name": "category2",
      "label": "Category 2",
      "required": false
    },
    {
      "name": "category3",
      "label": "Category 3",
      "required": false
    }
  ],
  "csv_headers": [
    "slug",
    "sku",
    "name",
    "price"
  ],
  "sample_row": {
    "slug": "widget",
    "sku": "W-1",
    "name": "Widget",
    "price": "10.00"
  },
  "mappings": [
    {
      "id": "immap_UkLWZg9DAJ",
      "schema_field": "slug",
      "file_column": "slug",
      "required": true
    },
    {
      "id": "immap_gbHJdmfrXB",
      "schema_field": "sku",
      "file_column": "sku",
      "required": true
    },
    {
      "id": "immap_EfhxLZ9ck8",
      "schema_field": "name",
      "file_column": "name",
      "required": true
    },
    {
      "id": "immap_VqXmZF31wY",
      "schema_field": "price",
      "file_column": "price",
      "required": true
    },
    {
      "id": "immap_uw2YK1rnl0",
      "schema_field": "status",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_OIJLhNcSbf",
      "schema_field": "description",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_AXs1igzRC6",
      "schema_field": "meta_title",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_p6klVeMgbn",
      "schema_field": "meta_description",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_nJqfPa3Cpe",
      "schema_field": "meta_keywords",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_98FqgRua4h",
      "schema_field": "tags",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_xhoCpeNMWu",
      "schema_field": "compare_at_price",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_vEmzDoNU0H",
      "schema_field": "currency",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_2KY5XM6frI",
      "schema_field": "width",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_HOVtlDrOmL",
      "schema_field": "height",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_ed6l8wVqSM",
      "schema_field": "depth",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_s18jaGonyx",
      "schema_field": "dimensions_unit",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_GZUcnUYI5A",
      "schema_field": "weight",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_ROeNhrwyV9",
      "schema_field": "weight_unit",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_L3pHOn63Vw",
      "schema_field": "available_on",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_PQNMcnNFWw",
      "schema_field": "discontinue_on",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_C9SrJgpzQ4",
      "schema_field": "track_inventory",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_YHETxCGlb0",
      "schema_field": "inventory_count",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_5OQZnCRf8J",
      "schema_field": "inventory_backorderable",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_F0GX8NaP3Y",
      "schema_field": "tax_category",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_kOKT9MVfb0",
      "schema_field": "shipping_category",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_3uWpPTcf5W",
      "schema_field": "image1_src",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_D6Psx31WaT",
      "schema_field": "image2_src",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_msx3nOJap6",
      "schema_field": "image3_src",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_5CQZnCRf8J",
      "schema_field": "option1_name",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_M2nyloHRUQ",
      "schema_field": "option1_value",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_prklVeMgbn",
      "schema_field": "option2_name",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_so8jaGonyx",
      "schema_field": "option2_value",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_rsClYtECFI",
      "schema_field": "option3_name",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_8DR0I7fEbw",
      "schema_field": "option3_value",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_aAtNvLSUAr",
      "schema_field": "category1",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_QiA48cIW7A",
      "schema_field": "category2",
      "file_column": null,
      "required": false
    },
    {
      "id": "immap_QDA48cIW7A",
      "schema_field": "category3",
      "file_column": null,
      "required": false
    }
  ]
}

{
  "error": {
    "code": "validation_error",
    "message": "Type can't be blank",
    "details": {
      "type": [
        "can't be blank"
      ]
    }
  }
}

API basics

Endpoints

Create an import

Authorizations

Headers

Body

Response