Skip to main content

Import Products

POST 
/api/v2/products/import

Imports run as a tracked job — a bulk import can exceed a ~100s edge-proxy limit (Cloudflare 524), so the rows are processed off the request cycle. Returns a tracked_job_log_id; progress and the created/updated/failed counts surface via the tracked job log endpoints.

Required scope: products:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Rows may include product_type — the product type's full path (e.g. Diapering > Cloth diapers), or just its leaf name when that name is unique among leaf types. A value that matches no type fails the row's validation. The import template includes this column.

Upsert by SKU: a row without a product id / existing_product_id updates the existing product with the same SKU (matched case-insensitively, keeping the stored spelling) instead of failing on the duplicate SKU; rows with a new SKU create products.

Product type on update: send _type_provided: true (as returned by Validate Import when the file maps a Type column) to change an existing product's type; without it an update keeps the product's current type, so a file with no Type column never turns a bundle or kit back into a standard product.

Components: component_skus / component_ids / component_of_sku / component_of_id use SKU->QTY, SKU2->QTY2; quantities may be decimals (default 1) and SKUs match case-insensitively. Linking replaces the product's whole component list.

Request​

Responses​

Accepted

Response Headers
    Content-Type