Product Lifecycle
List Lifecycle States
Every lifecycle state (the three system states plus any custom ones), each with its product count and its resolved policy for every business process. The response also carries `reasons` (the lifecycle reasons a change can record, as {value, label}) and `colors` (the colours a state may use) next to `data`.
Create Lifecycle State
Create a custom lifecycle state. Its key is derived from the label (lower-case, underscores, max 30 characters, suffixed _2, _3… when taken) and it starts with a copy of another state's policies, which you can then change with Save Lifecycle State Policies. Custom states sort after existing ones.
Update Lifecycle State
Rename, recolour, re-sort or change the auto-return of a state. System states can be relabelled and recoloured too. Send only the fields you want to change.
Delete Lifecycle State
Delete a custom lifecycle state. System states (active, phasing_out, discontinued) cannot be deleted. When products are still in the state you must name `reassign_to`; every product is then moved to that state and gets a history entry noting the deletion.
Preview Lifecycle State Policy Changes
See what a policy change would do before saving it: how many products are in the state and, for each process whose value would actually change, the current and proposed value labels. Nothing is saved.
Save Lifecycle State Policies
Save new policy values for a state. Only the processes you send change; the rest keep their current value. When products are in the state, a background job re-applies the policy to them (for example re-syncing channel quantities) and its id is returned as `tracked_job_id` next to `data`; it is null when the state has no products.
Reset Lifecycle State Policies
Put a system state's policies back to their defaults (custom states have no defaults and return 422). When products are in the state, a background job re-applies the policy and its id is returned as `tracked_job_id`; null otherwise. No body.
Get Product Lifecycle
A product's current lifecycle: its state, reason and dates, who changed it, its successor and predecessors, any pending scheduled change, its recent history and — for a matrix parent — each variant's state and a rollup. Archived products are included.
Change 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).
Preview Product Lifecycle Change
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.
Bulk Change Product Lifecycle
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.
Undo Lifecycle Change
Reverse a lifecycle change and restore the previous state, reason, note and dates. The whole change is undone together: every product moved by the same operation (a matrix parent and the variants that moved with it, or a variant and its re-derived parent) is reverted in one step, or none is. Matrix parents of the reverted products that were not part of the change are re-derived afterwards. A history entry with source undo is recorded for each product. No body.
List Product Lifecycle History
A product's full lifecycle history, newest first, paginated (10 per page by default, up to 200). Each entry says whether it can still be undone.
List Cancelled Lifecycle Schedules
A product's scheduled lifecycle changes that were cancelled - the latest 50, most recently cancelled first, not paginated. Each one keeps its note, which says why it was cancelled (for example cancelled by hand, replaced by a newer schedule, or cancelled because the product was archived). Use it alongside List Product Lifecycle History to show changes that were planned but never happened.
Get Product Succession Chain
The chain of 'replaced by' links through a product, oldest first: up to 5 predecessors before it and 5 successors after it. Where a product replaced several predecessors, the chain follows the most recent link.
List Lifecycle Schedules
Pending scheduled lifecycle changes across all products, soonest first, paginated. Only pending schedules are listed. Next to the pagination keys the response includes `creators` — the users who created a pending schedule, as {value: user id, title: name} — for filtering by creator.
Update Lifecycle Schedule
Change a pending schedule's date and/or target state. Send at least one of the two. A date of today applies the change straight away (the returned schedule then has status applied). Moving the target to phasing_out requires the schedule to already carry a discontinue date; moving it to phasing_out or discontinued without a reason records brand_decision. A phasing_out schedule must start before its discontinue date.
Cancel Lifecycle Schedule
Cancel a pending scheduled lifecycle change. The schedule is kept with status cancelled; the product's state is not touched. Only pending schedules can be cancelled.
List Product Successors
Every 'replaced by' link between products, newest first, paginated, with both products' SKU, name and lifecycle state.
Create Product Successor
Record that one product is replaced by another. A product has at most one successor, so this replaces the predecessor's existing link if it has one. Chains are allowed but may not loop back on themselves. Optionally discontinue the predecessor now or phase it out until a date in the same step (recorded with reason replaced). When auto_substitute is on, an order-time substitution rule from the predecessor to the successor is created or updated.
Update Product Successor
Change a successor link. Send only the fields to change. Changing the successor removes the substitution rule that was created for the old one; the auto-substitute rule is kept in sync with auto_substitute.
Delete Product Successor
Remove a successor link. The substitution rule created for it by auto_substitute is removed too; substitution rules you created yourself are left alone. For matrix styles, the variant links that were paired with this link are removed too. Neither product's lifecycle state changes.
List Lifecycle Suggestions
Paginated lifecycle suggestions: signals (dormant stock, discontinued suppliers, low-value erratic demand, inactive listings, ended seasons, a selling successor) that suggest moving a product to another lifecycle state. Suggestions are never applied automatically. Only open suggestions are returned unless you filter on status. The first call for an account that has never generated suggestions queues the first generation run in the background.
Get Lifecycle Suggestion Summary
Counts of open lifecycle suggestions, overall and per rule, plus each rule's effective configuration. Like the list, the first call for an account that has never generated suggestions queues the first run.
Accept Lifecycle Suggestion
Returns the prefilled lifecycle change for an open or snoozed suggestion. Nothing changes yet: submit the returned to_state, reason, note and source ('suggestion') to the change-lifecycle endpoint for the product to apply it, and the suggestion is then marked accepted automatically.
Mark Lifecycle Suggestion Accepted
Marks an open or snoozed suggestion as accepted without changing the product, for when the change was already made another way. Records who resolved it and when.
Dismiss Lifecycle Suggestion
Dismisses an open or snoozed suggestion with a reason. The same rule will not suggest a change for this product again for 180 days (suppressed_until).
Snooze Lifecycle Suggestion
Snoozes an open or snoozed suggestion for 30, 60 or 90 days. When the snooze ends, the suggestion reopens if its signal still holds at the next generation run.
Get Lifecycle Overview
Summary of products that are leaving the range (every state where demand planning is capped or excluded, such as Phasing out and Discontinued): stat cards, per-state totals, sell-through status counts, prioritised items needing action this week, upcoming dated events and chart series. Also queues the first lifecycle suggestions run if the account has never had one.
List 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.
Export Lifecycle Sell-through
Exports sell-through rows as CSV, either an explicit selection of product ids or every row matching the same filters and sort as the list. Up to 1,000 rows the CSV downloads directly (200, text/csv, file name product-lifecycle-sell-through-YYYY-MM-DD.csv). Above 1,000 rows the export runs as a background job and the response is 202 with the tracked job id and row count; when the job finishes, download the file with the export download endpoint (the job result carries its download URL).
Download Lifecycle Sell-through Export
Downloads a finished background sell-through export as CSV. Only the user who started the export, or an account admin, can download it; anyone else gets 404.
List FBA Sell-through Checklist
Paginated FBA wind-down checklist: one row per exiting product (a state where demand planning is capped or excluded) and Amazon account that still holds FBA units, with the checklist steps ticked so far and the aged-inventory surcharge clock for that account. Archived products are excluded. The response also carries `instances`: every Amazon account that appears on the checklist ([{value: integration instance id, title: name}]).
Update FBA Sell-through Checklist Steps
Ticks or unticks FBA wind-down checklist steps for one product on one Amazon account. Ticking records who completed the step and when; steps you leave out are unchanged.
Update FBA Surcharge Exemption
Overrides whether a product is exempt from Amazon's 181-270-day aged-inventory surcharge bands, which changes its FBA surcharge clock. By default the exemption follows the product's Amazon product type; send null to go back to that.
List Lifecycle Channel Behaviours
What ending or deleting a listing does on each connected sales channel when a product sells out or leaves the range, plus Shopify-specific capabilities. Read-only facts used to choose sell-out actions in the lifecycle settings.
List Shopify Store Collections
Collections in one connected Shopify store, optionally filtered by a search term. Use a collection's id as the fallback redirect target in the lifecycle settings: when an archived product has no live successor on the store, its storefront URL redirects to that collection. Results are cached for 5 minutes per store and search term.
Create Lifecycle Shopify Redirects
Creates Shopify URL redirects now for archived or sold-out products, so each product's old /products/<handle> storefront URL forwards to its first live successor on that store, or to the fallback collection when there is none. Runs immediately for each Shopify listing of each product and reports a per-product outcome; up to 200 products per call.
Retry Lifecycle Sell-out
Queue the sell-out action again for products whose last sell-out run failed or was stopped, once the channel problem behind it is fixed, instead of waiting for the nightly sweep. The sell-out action is what ends or deletes channel listings and archives a product when it sells out in a state whose policy says so. This call only queues the runs; each one re-checks the product and its listings when it runs.
List Clearance Plans
List clearance plans — markdown ladders that step discontinued or phasing-out products down to sell-out. Active plans are returned by default; use filter[archived] for ended ones.
Create Clearance Plan
Create a clearance plan, enrol its products and run the first evaluation straight away, so step-1 markdown suggestions are ready for review (or applied, with auto_apply).
Get Clearance Plan Template
Get the default 'Standard 3-step' markdown ladder (25% straight away, 40% once sell-through is behind plan after 3 weeks, 60% 21 days later) and the catalogue of step triggers with their meaning. A plan created without steps uses this ladder.
Get Clearance Plan
Get one clearance plan with its markdown ladder, its tiers and channels by name, and the projected markdown cost.
Update Clearance Plan
Change an active plan's settings or ladder. Partial: send only the fields that change. Sending steps replaces the whole ladder. Adding a price tier saves the enrolled products' current price in that tier as their original price. Narrowing the scope — removing a price tier from price_tier_ids or a channel from integration_instance_ids — takes those listings out of the plan: for products the plan already marked down, the compare-at ('was') price it set is cleared on those listings (pushed straight away and retried on later price pushes until the channel confirms), and open suggestions for a removed price tier are skipped with the reason 'Price tier removed from the plan'. Ended plans cannot be changed (422).
End Clearance Plan
End a clearance plan. The plan is not deleted: it moves to ended (listed with filter[archived]=1) and its open suggestions are closed.
List Clearance Plan Products
List the products enrolled in a plan with their sell-through, ladder step and prices.
Add Clearance Plan Products
Enrol more products in an active plan, by id or by a products-list filter. Each product's current price in the plan's tiers is saved as its original price. Products already in another active plan, or with no price in the plan's tiers, are skipped. Adding a product that was removed from this plan earlier lifts its removal, so the plan's filter can pick it up again. When anything was added the plan is evaluated straight away, so due markdowns are suggested.
Remove Clearance Plan Products
Take products out of a plan. Their current (clearance) price stays as it is; their open suggestions are skipped with the reason 'Removed from the plan'. For each removed product the plan had already marked down, the compare-at ('was') price the plan set is cleared on every listing it touched: the clear is pushed to the channels straight away and retried on later price pushes until each channel confirms it.
List Clearance Plan Suggestions
List a plan's markdown suggestions — one per product, price tier and due step — ordered pending, held, applied, skipped, then oldest first. A suggestion is held when its price breaks the plan floor or a pricing guardrail; held_reason says why, with amounts in the price's currency (e.g. 'Below landed cost ($18.40)', 'Pricing guardrail “MAP”: below its floor of €80.00').
Apply Clearance Suggestions
Approve markdown suggestions and apply their prices in the background. For each suggestion the price is written to its tier, the compare-at ('was') price is locked at the first reduction, and the product advances to that step; the new prices are then pushed to the plan's channels. Returns 202 with a tracked job id to follow progress.
Skip Clearance Suggestions
Skip markdown suggestions. Prices stay unchanged and a skipped step is not suggested again for that product; the next step can still become due.
Evaluate Clearance Plan
Run today's evaluation of a plan now instead of waiting for the daily run. A filter-scoped plan first re-runs its filter and enrols newly matching products. Then, for each product with stock and no open suggestion, the next unskipped step is checked against its trigger and a suggestion is created per price tier when due (held when it breaks the floor or a guardrail). With auto_apply on, unheld suggestions are applied immediately.
List Product Price History
List every recorded price of a product, newest first: changes to its price tiers and the prices pushed to each sales channel, with the compare-at ('was') price sent alongside. This is the record behind compliant reference prices (lowest price in the last 30 days, or a regular price held for a substantial period).
List Seasons
Paginated seasons with the number of products linked to each.
Create Season
Create a season.
Update Season
Replace a season's details. Send the full set of fields — code and name are required on every update.
Delete Season
Delete a season. If products are still linked the call fails with 422 unless detach=true is sent, which unlinks those products first (the products themselves are not changed).
Preview End of Season
Show which products would be ended with the season and what changing them would affect, without changing anything.
End Season
Move the season's selected candidates to Phasing out or Discontinued in a background job named 'Ending season <code>'. Each product's lifecycle change cascades to its variants and is recorded with the reason 'seasonal end'. When notify_customers is true, one discontinuation notice per buyer is queued after the job finishes.
Get Product Seasons
The seasons a product belongs to, plus its NOOS (never out of stock / core) flag.
Update Product Seasons
Replace the full list of seasons a product belongs to. Seasons not in the list are unlinked; an empty list removes every season.
Update Product NOOS Flag
Pin a product as never out of stock (core) or clear the flag. A hand-set value is marked manual, so the nightly NOOS classification no longer overwrites it. NOOS products are never offered as end-of-season candidates. To hand the flag back to the nightly classification, use Clear Product NOOS Pin.
Clear Product NOOS Pin
Remove a hand-set NOOS (never out of stock) pin so the product follows the automatic NOOS rule again: in stock on at least 80% of the last 180 days. The rule is applied straight away, so the flag returned is the one the nightly classification will keep. No body.
List Closeout Rows
The products a closeout selection covers, with available units and wholesale, clearance and MSRP prices — the same rows the CSV, linesheet and offer email contain. Read-only.
Export Closeout CSV
Download the closeout rows as a CSV file (closeout-<Y-m-d>.csv). Columns: SKU, Product, Attributes, Image URL, Units available, Wholesale price, Clearance price, MSRP, Case pack. Prices use two decimals; empty cells mean no price on that tier.
Generate Closeout Linesheet PDF
Render the closeout rows as a PDF linesheet (closeout-linesheet-<Y-m-d>.pdf, returned inline) using the tenant's Closeout linesheet PDF template. Returns 422 when no such template is set up.
Create Closeout Catalog
Create a customer portal catalog that shows only products in the chosen lifecycle states (for example Discontinued) - kept up to date as products change state - or only a fixed list of products (product_ids), and optionally assign it to customers. When product_pricing_tier_id is sent, every assigned customer is also moved onto that pricing tier (typically a clearance price list), replacing their current tier.
Send Closeout Offer
Check that the offer can reach someone, then queue a closeout offer email to each selected customer, listing the selected products with units and prices. Emails go out in a background job, one per customer, to the customer's email (or billing email when the main one is missing or invalid). They use the store's editable Closeout offer email template (Settings → Email Templates); if that template is switched off, no email is sent. Customers without a valid address, or whose store has the template switched off, are skipped and listed in the response. Each sent offer is logged on the customer's activity history. Before anything is queued the request is refused with 422 when the selection matches no products with stock (on selection), when none of the customers can be emailed (on customer_ids, saying how many have no valid address and how many belong to stores with the template switched off), or when the linesheet is needed - attach_linesheet, or a template that links to it - but no Closeout linesheet PDF template exists (on attach_linesheet).