Spree Admin SDK
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://your-store.com',
secretKey: 'sk_xxx',
})
// Upload the CSV with `client.files.upload(file, { visibility: 'private' })`
// first and pass its `signed_id`. The import then waits in `mapping`, with the
// columns assigned automatically.
const productImport = await client.imports.create({
type: 'products',
attachment_signed_id: 'eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a1b2c3',
})spree api post /imports -d '{"type":"products","attachment_signed_id":"eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a1b2c3"}'{
"id": "imp_gbHJdmfrXB",
"number": "IM1002",
"rows_count": 0,
"created_at": "2026-01-15T12:00:00.000Z",
"updated_at": "2026-01-15T12:00:00.000Z",
"type": "products",
"status": "mapping",
"store_id": "store_UkLWZg9DAJ",
"seller_id": null,
"user_id": "adm_UkLWZg9DAJ",
"processing_errors": null,
"delimiter": ",",
"price_list_id": null,
"seller_name": null,
"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": "stock_location",
"label": "Stock Location",
"required": false
},
{
"name": "tax_category",
"label": "Tax Category",
"required": false
},
{
"name": "product_type",
"label": "Product Type",
"required": false
},
{
"name": "hs_code",
"label": "HS Code",
"required": false
},
{
"name": "country_of_origin",
"label": "Country of Origin",
"required": false
},
{
"name": "customs_description",
"label": "Customs Description",
"required": false
},
{
"name": "carton",
"label": "Carton",
"required": false
},
{
"name": "units_per_carton",
"label": "Units per Carton",
"required": false
},
{
"name": "carton_weight",
"label": "Carton Weight",
"required": false
},
{
"name": "cartons_per_pallet",
"label": "Cartons per Pallet",
"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": "stock_location",
"file_column": null,
"required": false
},
{
"id": "immap_kOKT9MVfb0",
"schema_field": "tax_category",
"file_column": null,
"required": false
},
{
"id": "immap_3uWpPTcf5W",
"schema_field": "product_type",
"file_column": null,
"required": false
},
{
"id": "immap_D6Psx31WaT",
"schema_field": "hs_code",
"file_column": null,
"required": false
},
{
"id": "immap_msx3nOJap6",
"schema_field": "country_of_origin",
"file_column": null,
"required": false
},
{
"id": "immap_5CQZnCRf8J",
"schema_field": "customs_description",
"file_column": null,
"required": false
},
{
"id": "immap_M2nyloHRUQ",
"schema_field": "carton",
"file_column": null,
"required": false
},
{
"id": "immap_prklVeMgbn",
"schema_field": "units_per_carton",
"file_column": null,
"required": false
},
{
"id": "immap_so8jaGonyx",
"schema_field": "carton_weight",
"file_column": null,
"required": false
},
{
"id": "immap_rsClYtECFI",
"schema_field": "cartons_per_pallet",
"file_column": null,
"required": false
},
{
"id": "immap_8DR0I7fEbw",
"schema_field": "image1_src",
"file_column": null,
"required": false
},
{
"id": "immap_aAtNvLSUAr",
"schema_field": "image2_src",
"file_column": null,
"required": false
},
{
"id": "immap_QiA48cIW7A",
"schema_field": "image3_src",
"file_column": null,
"required": false
},
{
"id": "immap_QDA48cIW7A",
"schema_field": "option1_name",
"file_column": null,
"required": false
},
{
"id": "immap_8cR0I7fEbw",
"schema_field": "option1_value",
"file_column": null,
"required": false
},
{
"id": "immap_oqlrKdXjaP",
"schema_field": "option2_name",
"file_column": null,
"required": false
},
{
"id": "immap_48Olu6p4zZ",
"schema_field": "option2_value",
"file_column": null,
"required": false
},
{
"id": "immap_qp31JYFduR",
"schema_field": "option3_name",
"file_column": null,
"required": false
},
{
"id": "immap_JgaEBgznCp",
"schema_field": "option3_value",
"file_column": null,
"required": false
},
{
"id": "immap_tXyJwvFCuK",
"schema_field": "category1",
"file_column": null,
"required": false
},
{
"id": "immap_NJzXvxTk8u",
"schema_field": "category2",
"file_column": null,
"required": false
},
{
"id": "immap_XLbb5HTmVa",
"schema_field": "category3",
"file_column": null,
"required": false
}
]
}{
"error": {
"code": "validation_error",
"message": "Type can't be blank",
"details": {
"type": [
{
"code": "blank",
"message": "can't be blank",
"specific": false
}
]
}
}
}Create an import
Queues a CSV import. Upload the file first via POST /api/v3/admin/files
and pass the returned signed_id as attachment_signed_id. 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
/
v3
/
admin
/
imports
Spree Admin SDK
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://your-store.com',
secretKey: 'sk_xxx',
})
// Upload the CSV with `client.files.upload(file, { visibility: 'private' })`
// first and pass its `signed_id`. The import then waits in `mapping`, with the
// columns assigned automatically.
const productImport = await client.imports.create({
type: 'products',
attachment_signed_id: 'eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a1b2c3',
})spree api post /imports -d '{"type":"products","attachment_signed_id":"eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a1b2c3"}'{
"id": "imp_gbHJdmfrXB",
"number": "IM1002",
"rows_count": 0,
"created_at": "2026-01-15T12:00:00.000Z",
"updated_at": "2026-01-15T12:00:00.000Z",
"type": "products",
"status": "mapping",
"store_id": "store_UkLWZg9DAJ",
"seller_id": null,
"user_id": "adm_UkLWZg9DAJ",
"processing_errors": null,
"delimiter": ",",
"price_list_id": null,
"seller_name": null,
"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": "stock_location",
"label": "Stock Location",
"required": false
},
{
"name": "tax_category",
"label": "Tax Category",
"required": false
},
{
"name": "product_type",
"label": "Product Type",
"required": false
},
{
"name": "hs_code",
"label": "HS Code",
"required": false
},
{
"name": "country_of_origin",
"label": "Country of Origin",
"required": false
},
{
"name": "customs_description",
"label": "Customs Description",
"required": false
},
{
"name": "carton",
"label": "Carton",
"required": false
},
{
"name": "units_per_carton",
"label": "Units per Carton",
"required": false
},
{
"name": "carton_weight",
"label": "Carton Weight",
"required": false
},
{
"name": "cartons_per_pallet",
"label": "Cartons per Pallet",
"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": "stock_location",
"file_column": null,
"required": false
},
{
"id": "immap_kOKT9MVfb0",
"schema_field": "tax_category",
"file_column": null,
"required": false
},
{
"id": "immap_3uWpPTcf5W",
"schema_field": "product_type",
"file_column": null,
"required": false
},
{
"id": "immap_D6Psx31WaT",
"schema_field": "hs_code",
"file_column": null,
"required": false
},
{
"id": "immap_msx3nOJap6",
"schema_field": "country_of_origin",
"file_column": null,
"required": false
},
{
"id": "immap_5CQZnCRf8J",
"schema_field": "customs_description",
"file_column": null,
"required": false
},
{
"id": "immap_M2nyloHRUQ",
"schema_field": "carton",
"file_column": null,
"required": false
},
{
"id": "immap_prklVeMgbn",
"schema_field": "units_per_carton",
"file_column": null,
"required": false
},
{
"id": "immap_so8jaGonyx",
"schema_field": "carton_weight",
"file_column": null,
"required": false
},
{
"id": "immap_rsClYtECFI",
"schema_field": "cartons_per_pallet",
"file_column": null,
"required": false
},
{
"id": "immap_8DR0I7fEbw",
"schema_field": "image1_src",
"file_column": null,
"required": false
},
{
"id": "immap_aAtNvLSUAr",
"schema_field": "image2_src",
"file_column": null,
"required": false
},
{
"id": "immap_QiA48cIW7A",
"schema_field": "image3_src",
"file_column": null,
"required": false
},
{
"id": "immap_QDA48cIW7A",
"schema_field": "option1_name",
"file_column": null,
"required": false
},
{
"id": "immap_8cR0I7fEbw",
"schema_field": "option1_value",
"file_column": null,
"required": false
},
{
"id": "immap_oqlrKdXjaP",
"schema_field": "option2_name",
"file_column": null,
"required": false
},
{
"id": "immap_48Olu6p4zZ",
"schema_field": "option2_value",
"file_column": null,
"required": false
},
{
"id": "immap_qp31JYFduR",
"schema_field": "option3_name",
"file_column": null,
"required": false
},
{
"id": "immap_JgaEBgznCp",
"schema_field": "option3_value",
"file_column": null,
"required": false
},
{
"id": "immap_tXyJwvFCuK",
"schema_field": "category1",
"file_column": null,
"required": false
},
{
"id": "immap_NJzXvxTk8u",
"schema_field": "category2",
"file_column": null,
"required": false
},
{
"id": "immap_XLbb5HTmVa",
"schema_field": "category3",
"file_column": null,
"required": false
}
]
}{
"error": {
"code": "validation_error",
"message": "Type can't be blank",
"details": {
"type": [
{
"code": "blank",
"message": "can't be blank",
"specific": false
}
]
}
}
}Authorizations
Secret API key for admin access
JWT token for admin user authentication
Body
application/json
Which dataset to import, as its shorthand: products, customers, product_translations, price_list_prices, purchase_orders, or a type an extension registers.
Example:
"products"
The signed_id of the uploaded CSV, from files.upload() with visibility: "private".
CSV column separator. Defaults to a comma.
Available options:
,, ;, |, Example:
","
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 allowed origins.
Example:
"https://admin.example.com/store_abc/settings/imports"
For price_list_prices imports: the price list the rows are merged into. Must belong to the current store; other types ignore it.
Response
import created in mapping state
Was this page helpful?
⌘I