States

States allow you to model finite state machines reflecting custom business logic. They are available for Orders, Line Items, Products, Reviews, Payments, QuoteRequests, StagedQuotes, and Quotes to define.

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, and LineItemState defined for LineItems and CustomLineItems.

Representations

State

StateDraft

StatePagedQueryResponse

StateReference

StateResourceIdentifier

StateTypeEnum

StateRoleEnum

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	Present on resources created after 1 February 2019 except for events not tracked.
`lastModifiedAt` DateTime	Date and time (UTC) the State was last updated.
`lastModifiedBy`BETA LastModifiedBy	Present on resources created after 1 February 2019 except for events not tracked.

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 predifined 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.
`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 `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` String	`"state"` References a State.
`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.

`id` String	Unique identifier of the referenced State. Either `id` or `key` is required.
`key` String	User-defined unique identifier of the referenced State. Either `id` or `key` is required.
`typeId` String	`"state"` References a State.

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:

200State

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 that (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:

200State

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 that (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.
`/^var[.][a-zA-Z0-9]+$/` Any string parameter matching this regular expression	Predicate parameter values. 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.
`offset` Int	Number of elements skipped.
`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.

Response:

200StatePagedQueryResponse

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 that (custom) line item gets after it's 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"
  } ]
}

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:

201Stateasapplication/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" : "test-state",
  "type" : "ProductState",
  "roles" : [ ],
  "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 that (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 is returned.
`actions` Array of StateUpdateAction	Update actions to be performed on the State.

Response:

200Stateasapplication/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" : 1,
  "key" : "Initial",
  "type" : "LineItemState",
  "roles" : [ ],
  "name" : {
    "en" : "Initial"
  },
  "description" : {
    "en" : "Initial is the first that (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 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 is returned.
`actions` Array of StateUpdateAction	Update actions to be performed on the State.

Response:

200Stateasapplication/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" : 1,
  "key" : "Initial",
  "type" : "LineItemState",
  "roles" : [ ],
  "name" : {
    "en" : "Initial"
  },
  "description" : {
    "en" : "Initial is the first that (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 actions

Change State key

Set State name

Set State description

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:

200State

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 that (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:

200State

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 that (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"
}