States

The commercetools platform allows you to model states of certain objects, such as orders, line items, products, reviews, and payments 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

id - String
key - String
A unique identifier for the state.
version - Number
createdAt - DateTime
createdBy - CreatedBy BETA
Present on resources created after 2019-02-01 except for events not tracked.
lastModifiedAt - DateTime
lastModifiedBy - LastModifiedBy BETA
Present on resources updated after 2019-02-01 except for events not tracked.
type - StateType
name - LocalizedString - Optional
A human-readable name of the state.
description - LocalizedString - Optional
A human-readable description of the state.
initial - Boolean
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.
builtIn - Boolean
Builtin states are integral parts of the project that cannot be deleted nor the key can be changed.
roles - array of StateRole - Optional
transitions - Array of Reference to State - Optional
Transitions are a way to describe possible transformations of the current state to other states of the same type (for example: 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.

StateDraft

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

key - String - Required
type - StateType - Required
name - LocalizedString - Optional
description - LocalizedString - Optional
initial - Boolean - Optional
roles - array of StateRole - Optional
transitions - Array of Reference to State - Optional

StateType

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

OrderState - Used by Orders
LineItemState - Used by LineItems and CustomLineItems in Carts and Orders
ProductState - Used by Products
ReviewState - Used by Reviews
PaymentState - Used by paymentStatus in Payments

StateRole

Values of the StateRole enumeration:

ReviewIncludedInStatistics - Used by Reviews.
This role only applies for the ReviewState StateType. When the state of a Review has this role, the review will be taken into account for rating statistics.
Return - Used by Orders in the update action transitionLineItemState.
This role only applies for the LineItemState StateType.

Get State by ID

Endpoint: /{projectKey}/states/{id}
Method: GET
OAuth 2.0 Scopes: view_states:{projectKey} (or, deprecated: view_orders:{projectKey})
Response Representation: State

Get State by Key

Endpoint: /{projectKey}/states/key={key}
Method: GET
OAuth 2.0 Scopes: view_states:{projectKey} (or, deprecated: view_orders:{projectKey})
Response Representation: State

Query States

Endpoint: /{projectKey}/states
Method: GET
OAuth 2.0 Scopes: view_states:{projectKey} (or, deprecated: view_orders:{projectKey})
Response Representation: PagedQueryResult with results containing an array of States
Query Parameters:

where - Query Predicate - Optional
sort - Sort - Optional
expand - Expansion - Optional
limit - Number - Optional
offset - Number - Optional

Create State

Endpoint: /{projectKey}/states
Method: POST
OAuth 2.0 Scopes: manage_states:{projectKey} (or, deprecated: manage_orders:{projectKey})
Request Representation: StateDraft
Response Representation: State

Update State by ID

Endpoint: /{projectKey}/states/{id}
Method: POST
OAuth 2.0 Scopes: manage_states:{projectKey} (or, deprecated: manage_orders:{projectKey})
Response Representation: State
Fields:

version - Number - Required
The expected version of the state on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
actions - Array of UpdateAction - Required
The list of update actions to be performed on the state.

Update State by Key

Endpoint: /{projectKey}/states/key={key}
Method: POST
OAuth 2.0 Scopes: manage_states:{projectKey} (or, deprecated: manage_orders:{projectKey})
Response Representation: State
Fields:

version - Number - Required
The expected version of the state on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
actions - Array of UpdateAction - Required
The list of update actions to be performed on the state.

Update Actions

Change state key

Set state name

Set state description

Change state key

The key must be unique for all states.

action - String - "changeKey"
key - String

Set state name

action - String - "setName"
name - LocalizedString

Set state description

action - String - "setDescription"
description - LocalizedString

Change State type

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

action - String - "changeType"
type - StateType

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.

action - String - "changeInitial"
initial - Boolean

Set transitions

Transitions are a way to describe possible transformations of the current state to other states of the same type (for example: 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.

action - String - "setTransitions"
transitions - Array of Reference to State - Optional

Set State roles

action - String - "setRoles"
roles - array of StateRole

Add State roles

action - String - "addRoles"
roles - array of StateRole

Remove State roles

action - String - "removeRoles"
roles - array of StateRole

Delete State by ID

Endpoint: /{projectKey}/states/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_states:{projectKey} (or, deprecated: manage_orders:{projectKey})
Response Representation: State
Query Parameters:

version - Number - Required

Delete State by Key

Endpoint: /{projectKey}/states/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_states:{projectKey} (or, deprecated: manage_orders:{projectKey})
Response Representation: State
Query parameters:

version - Number - Required