Skip to main content

Execute Import

POST 
/api/v2/products/import

Executes the import — creates new products or updates existing ones (matched by existing_product_id or id) inside a single DB transaction.

Route: v2.products.import.import

Required body field:

  • products: array (min 1) of validated product objects produced by the validate endpoint.

SKU-8009 added the _image_urls field to each product object:

  • _image_urls: array<{ url: string, is_primary: bool, sort_order: int, download: bool }> | null
    • When non-null and non-empty, the import calls CreateUpdateProductService::addImages() which REPLACES the product's existing images with the supplied set.
    • When null or empty, existing product images are LEFT UNCHANGED (allowing partial column mapping without wiping image data).
    • Exactly one entry should have is_primary=true (the validate endpoint guarantees this; if not, the first entry is auto-promoted).
    • download=true causes the server to fetch and store the image bytes from the URL.

Response: 201 Created on success, 422 Unprocessable Entity on failure.

Success shape: { created: [{id, sku, name}], updated: [{id, sku, name}], errors: [] } Failure shape: { message: "Import failed: ..." } (transaction is rolled back).

Stock UoM (added 2026-05-30): stock_uom_code is now a supported field. Provide a value matching an existing UoM code (e.g. EACH, KG, BOX). On create, it sets the product's initial stock UoM; on update, it flips the stock UoM to the matching uom_id.

Request​

Responses​

Successful response