Skip to main content

Create Lifecycle State

POST 

/api/v2/product-lifecycle/states

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.

Required scope: products:write

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

Body:

  • label (required, string, max 60, unique across states)
  • color (optional): one of grey, blue, green, orange, red, purple, teal; default grey
  • description (optional, string, max 500)
  • copy_policies_from (optional, string): key of an existing state whose policies to copy; default active
  • auto_return (optional, object): move products back automatically
    • auto_return.after_days (optional, integer 1–3650): days in this state before returning
    • auto_return.to_state (optional, string): existing state key to return to (defaults to active when after_days is set). 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​

OK

Response Headers
    Content-Type