States
States allow you to model finite state machines that reflect your custom business logic.
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.
States are available for the following resources:
By default, each Project has a 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 |
|
builtIn Boolean |
|
roles Array of StateRoleEnum | Roles the State can fulfill for Reviews and Line Items. |
transitions Array of StateReference |
|
createdAt | Date and time (UTC) the State was initially created. |
createdBy BETA | IDs and references that created the State. |
lastModifiedAt | 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 true |
roles Array of StateRoleEnum | If suitable, assign predifined roles the State can fulfill in case the State's |
transitions Array of StateResourceIdentifier | Define the list of States of the same
|
StatePagedQueryResponse
PagedQueryResult with results
containing an array of State.
limit Int | Number of results requested. |
offset Int | Number of elements skipped. |
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 |
results Array of State | States matching the query. |
StateReference
id String | Unique identifier of the referenced State. |
typeId | "state" References a State. |
obj | Contains the representation of the expanded State. Only present in responses to requests with Reference Expansion for States. |
StateResourceIdentifier
ResourceIdentifier to a State. Either id
or key
is required. If both are set, an InvalidJsonInput error is returned.
StateTypeEnum
Resource or object type the State can be assigned to.
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.
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
Deprecated OAuth 2.0 scope: view_orders:{projectKey}
view_states:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
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
Deprecated OAuth 2.0 scope: view_orders:{projectKey}
view_states:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
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
Deprecated OAuth 2.0 scope: view_orders:{projectKey}
view_states:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
where | The parameter can be passed multiple times. |
/^var[.][a-zA-Z0-9]+$/ Any string parameter matching this regular expression | Predicate parameter values. 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. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to Default: true |
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
Checks if a State exists for a given 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 |
|
id String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/states/{id} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Check if State exists by Key
Checks if a State exists for a given 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 String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/states/key={key} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Check if State exists by Query Predicate
Checks if a State exists for a given Query Predicate. Returns a 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 |
|
where |
curl --head https://api.{region}.commercetools.com/{projectKey}/states -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Create State
Deprecated OAuth 2.0 scope: manage_orders:{projectKey}
manage_states:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
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
Deprecated OAuth 2.0 scope: manage_orders:{projectKey}
manage_states:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
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
Deprecated OAuth 2.0 scope: manage_orders:{projectKey}
manage_states:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
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 |
{"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 If When performing a |
{"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
Deprecated OAuth 2.0 scope: manage_orders:{projectKey}
manage_states:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
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
Deprecated OAuth 2.0 scope: manage_orders:{projectKey}
manage_states:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
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"}