Skip to main content

Bulk Change Product Lifecycle

POST 

/api/v2/products/lifecycle/bulk

Change the lifecycle of many products at once, as a background job. Select explicit ids, or set apply_to_all with the products-list filters to target every matching product. Each product is processed on its own, so one failure does not block the rest; a future effective_on schedules each change. The response returns the background job id to follow progress and the number of products selected. Changes are recorded with source bulk unless you send source suggestion or automation.

Required scope: products:write

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

Body:

  • ids (array of product ids): required unless apply_to_all is true
  • apply_to_all (optional, boolean)
  • filters (optional, object): products-list filters used with apply_to_all
  • 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 the change is recorded with source bulk.

Response fields: tracked_job_id, product_count.

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