Skip to main content

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.

Required scope: products:write

Grant 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​

OK

Response Headers
    Content-Type