Skip to main content

Bulk Create Products from Configurable Products

POST 

/api/configurable-products/bulk-create

Create products for several configured SKUs at once, each with the configured SKU as its SKU. One row failing never stops the rest.

Required scope: products:write

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

Authentication: Requires Bearer token (scope products:write). Moving open order lines (relink_open_lines) also needs the orders:write scope and permission to update sales orders; without them the products are still created and the lines stay where they are, with the reason in each row's message.

Body:

  • ids (integer[], required, 1–2,000, distinct) — configured SKU IDs. Selecting every row that matches a filter: send the matching IDs in ids, at most 2,000 per request; split a larger selection into several requests.
  • name_overrides (object, optional) — product name per configured SKU ID, e.g. {"42": "Black cover, 3:1 wire, long edge"}. IDs without an override get <base product name> — <visible option values>.
  • copy_from_base_product (boolean, optional, default true).
  • relink_waiting_lines (boolean, optional, default true) — attach order lines held without a product (waiting for this configured SKU) to the new product.
  • relink_open_lines (boolean, optional, default true) — also move open order lines still booked to the base product onto the new product. Only lines that are safe to move are moved (the same rules as Re-link Open Lines to Mapped Product); the order total and tax stay exactly as the channel charged.
  • recipe (object, optional) — also create the product's recipe (bill of materials), using the base product as its single component, and activate it as the default:
    • recipe.create (boolean) — must be true to build a recipe.
    • recipe.component_quantity (number > 0, max 1,000,000, default 1) — base product quantity per unit.
    • recipe.operations[] (max 50) — steps from the operations library: operation_template_id (integer, required) and option_names (string[], max 50, optional) — the line option names the step shows on its manufacturing orders (for example Punching Pattern).
    • recipe.operations_by_option_value[] (max 200) — steps added only when the configured SKU's options carry a given value: option_name (string, required), option_value (string, required), operation_template_id (integer, required). The step shows that option on its manufacturing orders.
  • apply_to_all, filters (optional) — accepted but ignored; ids decides what is created.

Response:

  • Up to 25 IDs: 200 with results[] — one row per ID: id, configured_sku, outcome (created, skipped when the SKU already exists or the row is already mapped, failed), product_id, message, bom_id, plus the open-line move counts: lines_moved, lines_skipped and lines_skipped_reasons (reason → count, lines left on the base product because moving them isn't safe), lines_failed and lines_failed_reasons (lines whose move raised an error), and lines_move_failed (true when the move could not run at all). Retry leftover lines with Re-link Open Lines to Mapped Product.
  • More than 25 IDs: 202 with tracked_job_id (also in data.tracked_job_log_id). The products are created by a background job; follow it with the tracked jobs endpoints. Its results carry summary, has_failures / failed_count (rows that failed to create plus rows whose line moves failed), errors[] and warnings[].

Returns 404 while line options are switched off.

Copy from base:

  • copy_fields (array, optional) — which base-product details to copy, from: brand, product_type, category, unit_of_measure, weight_dimensions, tax, accounting_codes, suppliers, images, tags_attributes, price. Omitted → the tenant's line_options.copy_from_base setting. An empty array copies nothing.
  • price_mode (string, optional) — base or base_plus_addons (base tier prices plus the option add-on prices recorded on the configured SKU's first order line; falls back to the base price when none was recorded). Omitted → the copy_price_mode setting. Only used when copy_fields includes price.
  • copy_from_base_product still works: false copies nothing; true or omitted uses copy_fields / the settings.
  • Suppliers copy with lead time, minimums, default flag, tax rate and tier costs; the supplier SKU is left blank. Images stored by SKU.io are duplicated; outside-URL images are shared.

Request​

Responses​

OK

Response Headers
    Content-Type