Skip to main content

Preview Product Lifecycle Change

POST 

/api/v2/products/lifecycle/preview

See what moving a selection of products to a state would touch before you commit: stock on hand and where it sits, products leaving demand planning, open purchase order lines and backorders, bundles and bills of materials that use them, live listings and how channel quantities change, recent B2B buyers, and the target state's policies. Nothing is changed.

Required scope: products:write

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

Body:

  • to_state (required, string): existing lifecycle state key
  • ids (array of product ids): required unless apply_to_all is true
  • apply_to_all (optional, boolean): use every product matching filters instead of ids
  • filters (optional, object): the same filters the products list accepts, used with apply_to_all
  • cascade (optional): all (default), same_state or selected — how matrix parents apply to their variants
  • variant_ids (optional, array of integers): variants to include when cascade is selected

Response fields: product_count (stock-holding products affected), target_ids (every product id the change applies to, variants included), to_state, on_hand_units, on_hand_value, by_location [{warehouse_id, name, type, units}], leaves_planning (products that would drop out of demand planning), open_po_lines {count, units, purchase_order_ids, line_ids}, open_backorders {count, units, sales_order_ids}, bundles_affected [{product_id, sku, name, type}], boms_affected (count of active bills of materials), listings {live, by_channel [{integration_instance_id, channel, count}]}, channel_effects (plain-language notes), b2b_buyers (B2B buyers who ordered these products within the notice look-back and would get a notice), notice_lookback_months (that look-back, from the product lifecycle settings), policies {process: value} for the target state, warnings (e.g. no stock left, so discontinuing applies the sell-out action straight away).

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

Request​

Responses​

OK

Response Headers
    Content-Type