Update Lifecycle State
PUT/api/v2/product-lifecycle/states/: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.
products:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body (all optional):
- label (string, max 60, unique across states)
- color: one of grey, blue, green, orange, red, purple, teal
- description (string or null, max 500)
- sort_order (integer 0–100000): display order
- auto_return (object or null): null clears auto-return
- auto_return.after_days (integer 1–3650 or null)
- auto_return.to_state (string or null): existing state key; a state cannot return to itself. Cannot be phasing_out (422: "A state cannot return to Phasing out automatically: phasing out needs a reason and a discontinue date. Return to another state, then phase products out by hand.")
State fields: key (stable identifier used in URLs and on products), label, description, color, is_system (true for active, phasing_out and discontinued, which cannot be deleted), sort_order, product_count (products currently in the state), auto_return (null, or {after_days, to_state}: products move back automatically after that many days), and policies — one entry per business process with process, label, help, value (current), value_label, default_value (the system default for this state), and allowed_values [{value, label}].
Requires a Bearer token with the products read/write scope and the settings.update permission.
Request
Responses
- 200
- 401
- 403
- 404
- 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.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
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.