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
- Stringkey
- String
A unique identifier for the state.version
- NumbercreatedAt
- DateTimecreatedBy
- CreatedBy BETA
Present on resources created after 2019-02-01 except for events not tracked.lastModifiedAt
- DateTimelastModifiedBy
- LastModifiedBy BETA
Present on resources updated after 2019-02-01 except for events not tracked.type
- StateTypename
- 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 aninitial
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 - Optionaltransitions
- Array of Reference to State - Optional
Transitions are a way to describe possible transformations of the current state to other states of the sametype
(for example: Initial -> Shipped). When performing atransitionState
update action andtransitions
is set, the currently referenced state must have a transition to the new state.
Iftransitions
is an empty list, it means the current state is a final state and no further transitions are allowed.
Iftransitions
is not set, the validation is turned off. When performing atransitionState
update action, any other state of the sametype
can be transitioned to.
StateDraft
A StateDraft is the representation to be given with a Create State request.
key
- String - Requiredtype
- StateType - Requiredname
- LocalizedString - Optionaldescription
- LocalizedString - Optionalinitial
- Boolean - Optionalroles
- array of StateRole - Optionaltransitions
- 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:
StateRole
Values of the StateRole
enumeration:
ReviewIncludedInStatistics
- Used by Reviews.
This role only applies for theReviewState
StateType. When thestate
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 theLineItemState
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 - Optionalsort
- Sort - Optionalexpand
- Expansion - Optionallimit
- Number - Optionaloffset
- 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
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.
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