List Lifecycle Sell-through
GET/api/v2/product-lifecycle/sell-through
Paginated sell-through metrics for every product in a state where demand planning is capped or excluded (for example Phasing out and Discontinued), excluding matrix parents: how much has sold since the product entered its state, what is left, the projected sell-out date against any clearance target, and the FBA aged-inventory surcharge clock. Also accepts POST with the same query-string parameters.
products:readGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Filters:
- filter[search]: matches id (exact), SKU or name; narrow with search_columns / search_strict_columns
- Text operators: sku, name
- Choice filters (is, is_not, is_one_of, is_not_one_of, is_empty, is_not_empty): lifecycle_state (state key), lifecycle_reason (brand_decision, supplier_discontinued, seasonal_end, low_performance, replaced, quality_issue, other), lifecycle_status (on_track, at_risk, stalled, sold_out, out_of_stock)
- Id filters (is, is_not, is_one_of, is_not_one_of): brand_id, category_id, supplier_id, integration_instance_id (has an active listing on that sales channel), warehouse_id (has stock in that warehouse), season_id (also is_empty / is_not_empty), clearance_plan_id
- filter[carryover] / filter[carryover.is]: true or false - products carried over between seasons
- filter[has_fba_stock.is]: true or false
- Numeric operators: id, sell_through_pct, on_hand, fba_units, stock_value, velocity_30d, weeks_of_cover, units_sold_since
- Date operators: since_at, projected_sell_out_on, target_sell_out_on, discontinue_on
- filter[archived]: only (archived products only) or all (include archived). Archived products are excluded by default.
Filter syntax: filter[<field>.<operator>]=<value>. A bare filter[<field>]=<value> means is where noted. Text operators: contains, does_not_contain, is, is_not, is_one_of, is_not_one_of, starts_with, does_not_start_with, ends_with, does_not_end_with, is_empty, is_not_empty. Numeric operators: is, is_not, is_one_of, is_not_one_of, greater_than, less_than, greater_than_or_equal, less_than_or_equal, between (two comma-separated values), is_empty, is_not_empty. Date operators: is, is_not, before, after, on_or_before, on_or_after, between, is_empty, is_not_empty, today, yesterday, tomorrow, past_week, past_month, past_year, next_week, next_month, next_year, days_ago, days_from_now, past_days, next_days. For AND/OR logic, send filter_groups as base64-encoded JSON: {"conjunction":"and","children":[{"type":"condition","condition":{"column":"sku.contains","operator":"contains","value":"TEE"}}]}.
Sort: id, sku, name, lifecycle_state, lifecycle_reason, since_at, units_at_discontinue, units_sold_since, units_received_since, sell_through_pct, on_hand, fba_units, stock_value, velocity_30d, weeks_of_cover, projected_sell_out_on, target_sell_out_on, lifecycle_status, discontinue_on. Prefix with - for descending. Default: -stock_value.
Pagination: page, per_page (1-500, default 10).
Row fields: id, sku, name, parent_id, attributes (variant attributes, name => value), lifecycle_state, state_label, state_color, since_at (when it entered the state, UTC), discontinue_on (scheduled discontinue date), lifecycle_reason, reason_label, units_at_discontinue (on hand when it entered the state), units_sold_since, units_received_since (purchase receipts and manufacturing output since), sell_through_pct (sold / (units at discontinue + received)), on_hand, fba_units, stock_value (at cost), velocity_30d (units per day over 30 days), weeks_of_cover, projected_sell_out_on, target_sell_out_on (earliest active clearance plan target), lifecycle_status (sold_out - nothing on hand, in transit, inbound to a channel warehouse, allocated to open orders or on open purchase orders, so the sell-out action can run; out_of_stock - nothing on hand, but units are still on the way or committed, or the state has no sell-out action; stalled - nothing sold in the last 30 days; at_risk - projected past the target; otherwise on_track), status_label, clearance (active clearance plan: plan_id, plan_name, current_step, steps; or null), successor (id, sku, name; or null), fba_clock, archived_at, sell_out_waiting_on (string array: for an out_of_stock row, why it is not sold out yet - e.g. "12 on open purchase orders", "3 allocated to open orders", "its lifecycle state has no sell-out action"; empty for every other status), sell_out_retryable (true when the product's last sell-out run failed or was stopped, so Retry Lifecycle Sell-out would queue it again).
fba_clock fields (null when the product has no FBA stock): product_id, fba_units, exempt (exempt from the 181-270-day surcharge bands), exemption_source (override, product_type, or null), product_types (Amazon product types behind the exemption), next_band_days (age in days at which the next band starts), next_band_date, days_until_next_band, next_band_units (units that will cross it), next_band_monthly_cost, current_monthly_cost, removal_deadline (last day a removal order avoids the next band - Amazon assesses on the 15th, so this is the 14th), label (human-readable summary).
Requires a Bearer token with the products read/write scope and the products.show permission.
Request
Responses
- 200
- 401
- 403
- 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.
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.