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.
products:writeGrant 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
filtersinstead 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
- 200
- 401
- 403
- 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.
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.