Skip to main content

Change Product Lifecycle

POST 

/api/v2/products/:product/lifecycle

Move a product to another lifecycle state — now, or on a future date. A future effective_on creates a pending schedule (replacing any pending schedule for the product) and the product keeps its current state until then; the message is then "Lifecycle change scheduled.". For a matrix parent the change also applies to its variants per cascade. The response is the product's updated lifecycle; transition_id is the id of the change just recorded (use it with Undo Lifecycle Change).

Required scope: products:write

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

Warnings (HTTP 200, status: warning, under warnings.lifecycle with code LifecycleWarning) are returned when, for example, open purchase orders still have units on order and you did not cancel them, or matrix variants had no matching successor variant so no history was transferred for them.

Body:

  • to_state (required, string, max 40): key of an existing lifecycle state (active, phasing_out, discontinued or a custom key)
  • effective_on (optional, date Y-m-d): today or later. A future date schedules the change instead of applying it; omit or use today to apply now
  • discontinue_on (date Y-m-d): required when to_state is phasing_out; must be after today. Phasing out also schedules the move to discontinued on this date
  • last_order_date (optional, date Y-m-d): last date the product can be ordered; on or before discontinue_on
  • reason (required when to_state is phasing_out or discontinued): brand_decision, supplier_discontinued, seasonal_end, low_performance, replaced, quality_issue, other
  • note (optional, string, max 500)
  • cascade (optional): how a matrix parent's change applies to its variants — all (default), same_state (only variants in the parent's current state) or selected (only variant_ids)
  • variant_ids (array of integers): required when cascade is selected
  • successor (optional, object): link the product that replaces this one in the same step
    • successor.product_id (required with successor, integer): existing product id
    • successor.pack_factor (optional, number > 0, max 1000000; default 1): successor units per predecessor unit
    • successor.history_transfer_pct (optional, integer 0–100; default 100): share of the predecessor's sales history credited to the successor for planning
    • successor.history_transfer_until (optional, date Y-m-d): stop transferring history after this date
    • successor.use_up_first (optional, boolean; default true): sell the predecessor's remaining stock before the successor
    • successor.auto_substitute (optional): none (default), when_unavailable or always — also create an order-time substitution rule
  • cancel_open_po_lines (optional, boolean): cancel the product's open purchase order lines. Needs purchase_orders.update (token scope purchase-orders:write)
  • cancel_open_backorders (optional, boolean): cancel its open backorders. Needs sales_orders.update (token scope orders:write)
  • notify_customers (optional, boolean): send the discontinuation notice to recent B2B buyers. Needs customers.send_communications (token scope customers:write)
  • source (optional): manual, suggestion or automation — any other value returns 422 "The source must be manual, suggestion or automation.". Send suggestion when acting on a lifecycle suggestion (it is marked accepted) and automation when your own rules made the change. Otherwise API tokens are recorded as api, and manual is accepted but recorded the same way.

Response fields: product_id, sku, name, type, archived_at, lifecycle_state, lifecycle_state_label, lifecycle_state_color, lifecycle_changed_at, lifecycle_reason (brand_decision, supplier_discontinued, seasonal_end, low_performance, replaced, quality_issue, other), lifecycle_reason_label, lifecycle_note, discontinue_on, last_order_date, discontinued_at, sold_out_at, lifecycle_archived_by_sell_out (true when the sell-out action archived it), changed_by {id, name} (who made the latest change), successor (the product that replaces this one, or null: id, sku, name, lifecycle_state, lifecycle_state_label, lifecycle_state_color, succession_id, pack_factor, history_transfer_pct, history_transfer_until, use_up_first, auto_substitute), predecessors (products this one replaces, same shape), schedule (the pending scheduled change, or null: id, product_id, product, from_state, from_state_label, to_state, to_state_label, effective_on, status, origin, discontinue_on, last_order_date, reason, note, cancel_reason (why it was cancelled, e.g. "Replaced by a new change on 2026-11-06"; null unless cancelled), created_by, created_at, cancelled_at - null unless the schedule was cancelled), rollup (matrix parents only, else null: total, counts {state: n}, dominant_state, dominant_label, dominant_color, dominant_count, partly, label such as "Partly discontinued · 3 of 8"), recent_transitions (latest changes, newest first — see List Product Lifecycle History for fields), variants (matrix parents only: id, sku, name, lifecycle_state, attributes {name: value}, lifecycle_state_label, lifecycle_state_color), longest_lead_time_days (longest supplier lead time; null for matrix parents), transition_id (on a change: the id of the transition just recorded, for undo; null when scheduled).

Scheduled changes (a future effective_on) keep the successor and the follow-up options and apply them on the effective date. A scheduled move to phasing_out needs a discontinue_on later than effective_on (422 "The discontinue date must be after the date the phase-out starts."); if the discontinue date has passed by the time the schedule runs, the phase-out is not applied.

Follow-up options need extra access: each one you set to true also needs the permission (and, for an API token, the scope) that guards the same action elsewhere — cancel_open_po_lines needs purchase_orders.update and the purchase-orders:write scope, cancel_open_backorders needs sales_orders.update and the orders:write scope, notify_customers needs customers.send_communications and the customers:write scope. Missing access returns 403 with a message naming it, e.g. "You need the purchase_orders.update permission to cancel open purchase order lines. Untick that option or ask an admin for the permission." or "This API token is missing the purchase-orders:write scope needed to cancel open purchase order lines.". When a scheduled change is applied, the follow-ups run as the user who scheduled it and are skipped if that user no longer has the permission.

Follow-up options the target state does not use are ignored rather than checked: notify_customers only applies when to_state is phasing_out or discontinued, and cancel_open_po_lines / cancel_open_backorders only for states that cancel open commitments (a move back to active never cancels anything). For any other state those options are treated as false - they need no permission, are not stored on a scheduled change, and do nothing.

Requires a Bearer token with the products read/write scope and the products.manage_lifecycle permission.

Request​

Responses​

OK

Response Headers
    Content-Type