Create Product Successor
POST/api/v2/product-successions
Record that one product is replaced by another. A product has at most one successor, so this replaces the predecessor's existing link if it has one. Chains are allowed but may not loop back on themselves. Optionally discontinue the predecessor now or phase it out until a date in the same step (recorded with reason replaced). When auto_substitute is on, an order-time substitution rule from the predecessor to the successor is created or updated.
products:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Matrix styles: when both products are matrix parents, one link per variant is also created, pairing variants on the attributes that tell them apart (e.g. Color + Size) with the same settings. The parent link is kept. Moving a predecessor to a different successor first removes the variant links paired with the old one. Variants with no matching variant on the successor get no link, and the response warns about them under warnings.lifecycle ("2 variants had no matching variant on the successor, so no history is transferred for them.").
Body:
- predecessor_product_id (required, integer): the product being replaced
- successor_product_id (required, integer): the replacement; must differ from the predecessor
- pack_factor (optional, number > 0, max 1000000; default 1): successor units per predecessor unit
- history_transfer_pct (optional, whole number 0–100; default 100)
- history_transfer_until (optional, date Y-m-d): defaults to 12 months after the phase-out date, the predecessor's discontinue date, or today
- use_up_first (optional, boolean; default true)
- auto_substitute (optional): none (default), when_unavailable, always
- discontinue_predecessor (optional): none (default), now (move it to discontinued) or phase_out (move it to phasing out)
- phase_out_until (date Y-m-d): required when discontinue_predecessor is phase_out — the date it becomes discontinued
Lifecycle warnings - unmatched matrix variants, or from changing the predecessor (e.g. open purchase orders still on order) - are returned under warnings.lifecycle with HTTP 200 and status: warning.
Successor link fields: id, predecessor_product_id, successor_product_id, predecessor and successor {id, sku, name, lifecycle_state, lifecycle_state_label, lifecycle_state_color}, pack_factor (successor units per predecessor unit), history_transfer_pct (share of the predecessor's sales history credited to the successor in planning), history_transfer_until (history stops transferring after this date), use_up_first (sell the predecessor's stock before the successor), auto_substitute (none, when_unavailable, always), product_substitution_id (the order-time substitution rule created for auto_substitute, or null), created_at.
Requires a Bearer token with the products read/write scope and the products.manage_lifecycle permission.
Request
Responses
- 200
- 401
- 403
- 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.
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.