States

The commercetools platform allows you to model states of certain objects, such as orders, line items, products, reviews, and payments in order to define finite state machines reflecting the business logic you’d like to implement.

States can be combined together by defining transitions between each state. transitionState update actions are validated to ensure the transition complies with the workflow definition.

If the transitions field is not set, no validation is performed. This is useful when an external system executes the workflow and the current state is to be saved.

By default each project has a builtin initial LineItemState defined for LineItems and CustomLineItems

Representations

State

StateDraft

A StateDraft is the representation to be given with a Create State request.

StateType

In a StateDraft it has to be specified to which CTP resource or object the state shall belong to.
The StateType enumeration contains values for each of the objects that can have states assigned:

StateRole

Values of the StateRole enumeration:

Get State by ID

Endpoint: /{projectKey}/states/{id}
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: State

Query States

Endpoint: /{projectKey}/states
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: PagedQueryResult with the results array of States
Query Parameters:

Create State

Endpoint: /{projectKey}/states
Method: POST
OAuth2 Scopes: manage_project:{projectKey}
Request Representation: StateDraft
Response Representation: State

Update State

Endpoint: /{projectKey}/states/{id}
Method: POST
OAuth2 Scopes: manage_orders:{projectKey}
Response Representation: State
Fields:

Update Actions
Please find below the individual update actions provided on this endpoint.


Change state key

The key must be unique for all states.

Set state name

Set state description

Change State type

A StateType indicates where the State is allowed to be used.

Change initial State

A state can be declared as an initial state for any state machine. When a workflow starts, this first state must be an initial state.

Set transitions

Transitions are a way to describe possible transformations of the current state to other states of the same type (e.g.: Initial -> Shipped). When performing a transitionState update action and transitions is set, the currently referenced state must have a transition to the new state.
If transitions is an empty list, it means the current state is a final state and no further transitions are allowed.
If transitions is not set, the validation is turned off. When performing a transitionState update action, any other state of the same type can be transitioned to.

Set State roles

Add State roles

Remove State roles

Delete State

Endpoint: /{projectKey}/states/{id}
Method: DELETE
OAuth2 Scopes: manage_orders:{projectKey}
Query Parameters: