Documentation

States

Elevate, May 20-22-2025, Miami Beach, Florida

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​
StateTypeEnum​

Indicates to which resource or object types the State is assigned to.

name​
LocalizedString​

Name of the State.

description​
LocalizedString​

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​
  • list of States of the same type that the current State can be transitioned to. For example, when the current State is the Initial State of StateType OrderState and this list contains the reference to the Shipped OrderState, the transition Initial -> Shipped is allowed.
  • if empty, no transitions are allowed from the current State, defining the current State as final for this workflow.
  • if not set, the validation is turned off and the current State can be transitioned to any other State of the same type as the current State.
createdAt​
DateTime​

Date and time (UTC) the State was initially created.

createdBy​BETA
CreatedBy​

IDs and references that created the State.

lastModifiedAt​
DateTime​

Date and time (UTC) the State was last updated.

lastModifiedBy​BETA
LastModifiedBy​

IDs and references that last modified the State.

StateDraft

key​
String​

User-defined unique identifier for the State.

type​
StateTypeEnum​

Specify to which resource or object type the State is assigned to.

name​
LocalizedString​

Name of the State.

description​
LocalizedString​

Description of the State.

initial​
Boolean​

Set to false if the State is not the first step in a workflow.

Default: 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.

  • If, for example, the current State is the Initial State of StateType OrderState and you want to allow the transition Initial -> Shipped, then add the StateResourceIdentifier to the Shipped OrderState to this list.
  • Set to empty list for not allowing any transition from the current State and defining it as final State for a workflow.
  • Do not set this field at all to turn off validation and allowing transitions to any other State of the same type as the current State.

StatePagedQueryResponse

PagedQueryResult with results containing an array of State.

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

Reference to a State.

id​
String​

Unique identifier of the referenced State.

typeId​
ReferenceTypeId​
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

ResourceIdentifier to a State. Either 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​
ReferenceTypeId​
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

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 its rating is taken into account for ReviewRatingStatistics. This role only applies for the ReviewState 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}

GET
https://api.{region}.commercetools.com/{projectKey}/states/{id}
OAuth 2.0 Scopes:
view_states:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the State.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

State

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/states/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Statejson
{
  "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}

GET
https://api.{region}.commercetools.com/{projectKey}/states/key={key}
OAuth 2.0 Scopes:
view_states:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the State.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

State

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/states/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Statejson
{
  "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}

GET
https://api.{region}.commercetools.com/{projectKey}/states
OAuth 2.0 Scopes:
view_states:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

Default: 20​
offset
​
Int
​

Number of elements skipped.

Default: 0​
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.
Response:
200

StatePagedQueryResponse

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/states -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: StatePagedQueryResponsejson
{
  "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

HEAD
https://api.{region}.commercetools.com/{projectKey}/states/{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.

OAuth 2.0 Scopes:
view_states:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the State.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/states/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if State exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/states/key={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.

OAuth 2.0 Scopes:
view_states:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the State.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/states/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if State exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/states

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.

OAuth 2.0 Scopes:
view_states:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
where
​
QueryPredicate
​

Query Predicates on States are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
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}

POST
https://api.{region}.commercetools.com/{projectKey}/states
OAuth 2.0 Scopes:
manage_states:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:StateDraftasapplication/json
Response:
201

State

asapplication/json
Request Example:cURL
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
201 Response Example: Statejson
{
  "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}

POST
https://api.{region}.commercetools.com/{projectKey}/states/{id}
OAuth 2.0 Scopes:
manage_states:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the State.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
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.

Response:
200

State

asapplication/json
Request Example:cURL
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
200 Response Example: Statejson
{
  "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}

POST
https://api.{region}.commercetools.com/{projectKey}/states/key={key}
OAuth 2.0 Scopes:
manage_states:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the State.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
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.

Response:
200

State

asapplication/json
Request Example:cURL
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
200 Response Example: Statejson
{
  "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.

Example: json
{
  "action": "changeKey",
  "key": "ChangedStateKey"
}

Set State name

action​
String​
"setName"
name​
LocalizedString​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action": "setName",
  "name": {
    "de": "State Name",
    "en": "State name"
  }
}

Set State description

action​
String​
"setDescription"
description​
LocalizedString​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action": "setDescription",
  "description": {
    "de": "State Beschreibung",
    "en": "State description"
  }
}

Change State type

action​
String​
"changeType"
type​
StateTypeEnum​

Resource or object types the State shall be assigned to. Must not be empty.

Example: json
{
  "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.

Example: json
{
  "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.

Example: json
{
  "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.

Example: json
{
  "action": "setRoles",
  "roles": [
    "ReviewIncludedInStatistics"
  ]
}

Add State roles

action​
String​
"addRoles"
roles​
Array of StateRoleEnum​

Value to append to the array.

Example: json
{
  "action": "addRoles",
  "roles": [
    "ReviewIncludedInStatistics"
  ]
}

Remove State roles

action​
String​
"removeRoles"
roles​
Array of StateRoleEnum​

Roles to remove from the State.

Example: json
{
  "action": "removeRoles",
  "roles": [
    "ReviewIncludedInStatistics"
  ]
}

Delete State

Delete State by ID

Deprecated OAuth 2.0 scope: manage_orders:{projectKey}

DELETE
https://api.{region}.commercetools.com/{projectKey}/states/{id}
OAuth 2.0 Scopes:
manage_states:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the State.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

State

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/states/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Statejson
{
  "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}

DELETE
https://api.{region}.commercetools.com/{projectKey}/states/key={key}
OAuth 2.0 Scopes:
manage_states:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the State.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

State

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/states/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Statejson
{
  "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"
}