Map Configurable Product to Product
POST/api/configurable-products/:id/map
Map a configured SKU to an existing product. Future order lines carrying this configured SKU are booked to that product.
products:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Authentication: Requires Bearer token (scope products:write).
Body:
product_id(integer, required) — an existing, unarchived product. It cannot be the base product itself: to say the configured SKU is just its base product, use Use Base Product for Configurable Product.relink_waiting_lines(boolean, optional, default true) — also link the order lines currently waiting on a product. Linking runs in the background in chunks and links each line in place;relinked_linesis the number of lines queued. A bundle can't be linked in place, so when the product is a bundle no lines are queued (relinked_linesis 0) anddata.waiting_lines_blocked_reasonsays to replace them manually.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, theorders:writescope. Without that the mapping still succeeds and the lines stay where they are (seeopen_lines.not_moved_reason).
Response: the updated configured SKU (data), 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.
Returns 422 when the product is archived or is the base product (then reason is base_product; otherwise reason is null), 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).
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not Found
Response Headers
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.