States allow you to model finite state machines that reflect your custom business logic.
transitions
between each State. transitionState
update actions are validated to ensure the transition complies with the workflow definition.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.States are available for the following resources:
builtin
, initial
, and LineItemState
defined for LineItems and CustomLineItems.Representations
State
id ​String​ | Unique identifier of the State. |
version ​Int​ | Current version of the State. |
key ​String​ | User-defined unique identifier of the State. |
type ​ | Indicates to which resource or object types the State is assigned to. |
name ​ | Name of the State. |
description ​ | Description of the State. |
initial ​Boolean​ | true for an initial State, the first State in a workflow. |
builtIn ​Boolean​ | true for States that are an integral part of the Project. Those States cannot be deleted and their key cannot be changed. |
roles ​Array of StateRoleEnum​ | Roles the State can fulfill for Reviews and Line Items. |
transitions ​Array of StateReference​ |
|
createdAt ​DateTime​ | Date and time (UTC) the State was initially created. |
createdBy ​BETACreatedBy​ | IDs and references that created the State. |
lastModifiedAt ​DateTime​ | Date and time (UTC) the State was last updated. |
lastModifiedBy ​BETA | IDs and references that last modified the State. |
StateDraft
key ​String​ | User-defined unique identifier for the State. |
type ​ | Specify to which resource or object type the State is assigned to. |
name ​ | Name of the State. |
description ​ | Description of the State. |
initial ​Boolean​ | Set to Default: false if the State is not the first step in a workflow.true ​ |
roles ​Array of StateRoleEnum​ | If suitable, assign predefined roles the State can fulfill in case the State's type is LineItemState or ReviewState . |
transitions ​Array of StateResourceIdentifier​ | Define the list of States of the same
type to which the current State can be transitioned to.
|
StatePagedQueryResponse
limit ​Int​ | Number of results requested. Default: 20 ​Minimum: 0 ​Maximum: 500 ​ |
offset ​Int​ | Number of elements skipped. Default: 0 ​Maximum: 10000 ​ |
count ​Int​ | Actual number of results returned. |
total ​Int​ | Total number of results matching the query.
This number is an estimation that is not strongly consistent.
This field is returned by default.
For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false .
When the results are filtered with a Query Predicate, total is subject to a limit. |
results ​Array of State​ | States matching the query. |
StateReference
id ​String​ | Unique identifier of the referenced State. |
typeId ​ | state Type of referenced resource. |
obj ​State​ | Contains the representation of the expanded State. Only present in responses to requests with Reference Expansion for States. |
StateResourceIdentifier
id
or key
is required. If both are set, an InvalidJsonInput error is returned.id ​String​ | Unique identifier of the referenced State. Required if key is absent. |
key ​String​ | User-defined unique identifier of the referenced State. Required if id is absent. |
typeId ​ | state Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource. |
StateTypeEnum
Resource or object type the State can be assigned to.
OrderState
- Used by Orders.
LineItemState
ProductState
- Used by Products.
ReviewState
- Used by Reviews.
PaymentState
- Used by PaymentStatus in Payments.
QuoteRequestState
- Used by QuoteRequest.
StagedQuoteState
- Used by StagedQuote.
QuoteState
- Used by Quote.
StateRoleEnum
For some resource types, a State can fulfill the following predefined roles:
ReviewIncludedInStatistics
- If a Review's
state
has this role itsrating
is taken into account for ReviewRatingStatistics. This role only applies for theReviewState
StateTypeEnum. Return
- Used by Orders in the update action transitionLineItemState. This role only applies for the
LineItemState
StateTypeEnum.
Get State
Get State by ID
view_orders:{projectKey}
view_states:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the State. |
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/states/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca",
"version": 1,
"key": "Initial",
"type": "LineItemState",
"roles": [],
"name": {
"en": "Initial"
},
"description": {
"en": "Initial is the first State that a (custom) Line Item gets after its creation."
},
"builtIn": true,
"initial": true,
"createdAt": "2015-01-21T09:22:03.906Z",
"lastModifiedAt": "2015-01-21T09:22:03.906Z"
}
Get State by Key
view_orders:{projectKey}
view_states:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the State. |
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/states/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca",
"version": 1,
"key": "Initial",
"type": "LineItemState",
"roles": [],
"name": {
"en": "Initial"
},
"description": {
"en": "Initial is the first State that a (custom) Line Item gets after its creation."
},
"builtIn": true,
"initial": true,
"createdAt": "2015-01-21T09:22:03.906Z",
"lastModifiedAt": "2015-01-21T09:22:03.906Z"
}
Query States
view_orders:{projectKey}
view_states:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
where | The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limit Int ​ | Number of results requested. Default: 20 ​Minimum: 0 ​Maximum: 500 ​ |
offset Int ​ | Number of elements skipped. Default: 0 ​Maximum: 10000 ​ |
withTotal Boolean ​ | Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.Default: true ​ |
var.<varName> String ​ | Predicate parameter values. The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/states -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"limit": 20,
"offset": 0,
"count": 2,
"total": 2,
"results": [
{
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca",
"version": 1,
"key": "Initial",
"type": "LineItemState",
"roles": [],
"name": {
"en": "Initial"
},
"description": {
"en": "Initial is the first State that a (custom) Line Item gets after its creation."
},
"builtIn": true,
"initial": true,
"createdAt": "2015-01-21T09:22:03.906Z",
"lastModifiedAt": "2015-01-21T09:22:03.906Z"
},
{
"id": "fb2b1abd-7598-40f1-906c-9e5e7c6f8ebc",
"version": 1,
"key": "test-state",
"type": "ProductState",
"roles": [],
"builtIn": false,
"initial": true,
"createdAt": "2016-02-18T17:18:53.338Z",
"lastModifiedAt": "2016-02-18T17:18:53.338Z"
}
]
}
Check if State exists
Check if State exists by ID
id
. Returns a 200 OK
status if the State exists or a 404 Not Found
otherwise.view_states:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the State. |
curl --head https://api.{region}.commercetools.com/{projectKey}/states/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if State exists by Key
key
. Returns a 200 OK
status if the State exists or a 404 Not Found
otherwise.view_states:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the State. |
curl --head https://api.{region}.commercetools.com/{projectKey}/states/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if State exists by Query Predicate
200 OK
status if any States match the query predicate, or a 404 Not Found
otherwise.view_states:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
where |
curl --head https://api.{region}.commercetools.com/{projectKey}/states -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Create State
manage_orders:{projectKey}
manage_states:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/states -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"key" : "Initial",
"type" : "LineItemState",
"roles" : [ ],
"name" : {
"en" : "Initial"
},
"description" : {
"en" : "Initial is the first State that a (custom) Line Item gets after its creation."
},
"initial" : true
}
DATA
{
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca",
"version": 1,
"key": "Initial",
"type": "LineItemState",
"roles": [],
"name": {
"en": "Initial"
},
"description": {
"en": "Initial is the first State that a (custom) Line Item gets after its creation."
},
"builtIn": true,
"initial": true,
"createdAt": "2015-01-21T09:22:03.906Z",
"lastModifiedAt": "2015-01-21T09:22:03.906Z"
}
Update State
Update State by ID
manage_orders:{projectKey}
manage_states:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the State. |
expand | The parameter can be passed multiple times. |
application/json
version ​Int​ | Expected version of the State on which the changes should be applied.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions ​Array of StateUpdateAction​ | Update actions to be performed on the State. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/states/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "setName",
"name" : {
"en" : "New Name"
}
} ]
}
DATA
{
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca",
"version": 2,
"key": "Initial",
"type": "LineItemState",
"roles": [],
"name": {
"en": "New Name"
},
"description": {
"en": "Initial is the first State that a (custom) Line Item gets after its creation."
},
"builtIn": true,
"initial": true,
"createdAt": "2015-01-21T09:22:03.906Z",
"lastModifiedAt": "2024-08-06T13:49:48.511Z"
}
Update State by Key
manage_orders:{projectKey}
manage_states:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the State. |
expand | The parameter can be passed multiple times. |
application/json
version ​Int​ | Expected version of the State on which the changes should be applied.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions ​Array of StateUpdateAction​ | Update actions to be performed on the State. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/states/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "setName",
"name" : {
"en" : "New Name"
}
} ]
}
DATA
{
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca",
"version": 2,
"key": "Initial",
"type": "LineItemState",
"roles": [],
"name": {
"en": "New Name"
},
"description": {
"en": "Initial is the first State that a (custom) Line Item gets after its creation."
},
"builtIn": true,
"initial": true,
"createdAt": "2015-01-21T09:22:03.906Z",
"lastModifiedAt": "2024-08-06T13:49:48.511Z"
}
Update actions
Change State key
action ​String​ | "changeKey" |
key ​String​ | New value to set. Must not be empty. |
{
"action": "changeKey",
"key": "ChangedStateKey"
}
Set State name
action ​String​ | "setName" |
name ​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setName",
"name": {
"de": "State Name",
"en": "State name"
}
}
Set State description
action ​String​ | "setDescription" |
description ​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setDescription",
"description": {
"de": "State Beschreibung",
"en": "State description"
}
}
Change State type
action ​String​ | "changeType" |
type ​ | Resource or object types the State shall be assigned to. Must not be empty. |
{
"action": "changeType",
"type": "ReviewState"
}
Change initial State
action ​String​ | "changeInitial" |
initial ​Boolean​ | Set to true for defining the State as initial State in a state machine and making it the first step in a workflow. |
{
"action": "changeInitial",
"initial": false
}
Set transitions
action ​String​ | "setTransitions" |
transitions ​Array of StateResourceIdentifier​ | Value to set. If empty, any existing value will be removed. 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": "setTransitions",
"transitions": [
{
"typeId": "state",
"id": "{{state-id}}"
},
{
"typeId": "state",
"id": "{{state-id2}}"
}
]
}
Set State roles
action ​String​ | "setRoles" |
roles ​Array of StateRoleEnum​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setRoles",
"roles": [
"ReviewIncludedInStatistics"
]
}
Add State roles
action ​String​ | "addRoles" |
roles ​Array of StateRoleEnum​ | Value to append to the array. |
{
"action": "addRoles",
"roles": [
"ReviewIncludedInStatistics"
]
}
Remove State roles
action ​String​ | "removeRoles" |
roles ​Array of StateRoleEnum​ | Roles to remove from the State. |
{
"action": "removeRoles",
"roles": [
"ReviewIncludedInStatistics"
]
}
Delete State
Delete State by ID
manage_orders:{projectKey}
manage_states:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the State. |
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/states/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca",
"version": 1,
"key": "Initial",
"type": "LineItemState",
"roles": [],
"name": {
"en": "Initial"
},
"description": {
"en": "Initial is the first State that a (custom) Line Item gets after its creation."
},
"builtIn": true,
"initial": true,
"createdAt": "2015-01-21T09:22:03.906Z",
"lastModifiedAt": "2015-01-21T09:22:03.906Z"
}
Delete State by Key
manage_orders:{projectKey}
manage_states:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the State. |
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/states/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca",
"version": 1,
"key": "Initial",
"type": "LineItemState",
"roles": [],
"name": {
"en": "Initial"
},
"description": {
"en": "Initial is the first State that a (custom) Line Item gets after its creation."
},
"builtIn": true,
"initial": true,
"createdAt": "2015-01-21T09:22:03.906Z",
"lastModifiedAt": "2015-01-21T09:22:03.906Z"
}