Update Product Successor
PUT/api/v2/product-successions/:succession
Change a successor link. Send only the fields to change. Changing the successor removes the substitution rule that was created for the old one; the auto-substitute rule is kept in sync with auto_substitute.
products:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Matrix styles: when both products are matrix parents, the variant links are paired again with the new settings (and, when the successor changes, the variant links to the old successor are removed first). Variants with no matching variant on the successor come back as warnings under warnings.lifecycle with HTTP 200 and status: warning.
Body (all optional):
- successor_product_id (integer): new replacement product; the change may not create a loop
- pack_factor (number > 0, max 1000000)
- history_transfer_pct (whole number 0–100)
- history_transfer_until (date Y-m-d or null): null removes the end date
- use_up_first (boolean)
- auto_substitute: none, when_unavailable, always
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
- 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.