Skip to main content

Create Product from Configurable Product

POST 

/api/configurable-products/:id/create-product

Create the product a configured SKU stands for and map it. The new product's SKU is always the configured SKU.

Required scope: products:write

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

Authentication: Requires Bearer token (scope products:write).

Body:

  • name (string, required, max 255).
  • copy_from_base_product (boolean, optional, default true) — copy brand, product type, categories, stock unit, weight, dimensions, tax code and nominal codes from the base product. Suppliers, prices, barcodes, images and listings are never copied.
  • relink_waiting_lines (boolean, optional, default true) — link the order lines waiting on a product (in the background; relinked_lines is the number queued).
  • relink_open_lines (boolean, optional, default true) — also move the open order lines still booked to the base product onto the product, keeping each line's price, discounts and tax. Only lines that are safe to move are moved (the same rules as Re-link Open Lines to Mapped Product). It runs only when the caller may edit sales orders: permission to update sales orders and, for a token, the orders:write scope. Without that the mapping still succeeds and the lines stay where they are (see open_lines.not_moved_reason).
  • 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.

Response (201): the updated configured SKU (data), the new product, bom_id (the recipe, or null), relinked_lines and open_lines.

open_lines — what happened to the open lines on the base product, or null when relink_open_lines was false: moved (lines moved onto the product), blocked and blocked_reasons ({reason: count}, lines left on the base product because moving them isn't safe), failed and failed_reasons (lines whose move raised an error), message (set when lines failed, with how to retry; otherwise null) and not_moved_reason ("Lines not moved: you don't have permission to edit sales orders." when the caller may not edit sales orders, with every count 0; otherwise null). Retry leftover lines with Re-link Open Lines to Mapped Product.

409 Conflict when a product with this SKU already exists (reason: sku_exists) or the configured SKU was mapped meanwhile (reason: already_mapped). The body names that product in product (and existing_product), so you can map to it instead.

Returns 422 when a recipe is requested but the configured SKU has no base product, the base product has no stock unit, or a step no longer exists; 404 when the configured SKU does not exist or line options are switched off.

open_lines.move_failed (boolean): true when the move itself failed. The counts are then unknown, and open_lines.message says why (the mapping or product is still saved; retry with Re-link Open Lines).

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​

Created

Response Headers
    Content-Type