States

The commercetools platform allows you to model states of certain objects, such as orders, line items, products, reviews, and payments in order 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 - String
  • version - Number
  • createdAt - DateTime
  • lastModifiedAt - DateTime
  • key - String
    A unique identifier for the state.
  • type - StateType
  • name - LocalizedString
    A human-readable name of the state.
  • description - LocalizedString
    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 an initial 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 - Optional
  • transitions - Array of Reference to State - Optional
    Transitions are a way to describe possible transformations of the current state to other states of the same type (e.g.: 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.

StateDraft

A StateDraft is the representation to be given with a Create State request.

StateType

In a StateDraft it has to be specified to which CTP 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 the ReviewState StateType. When the state 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 the LineItemState StateType.

Get State by ID

Endpoint: /{projectKey}/states/{id}
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: State

Query States

Endpoint: /{projectKey}/states
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: PagedQueryResult with the results array of States
Query Parameters:

Create State

Endpoint: /{projectKey}/states
Method: POST
OAuth2 Scopes: manage_project:{projectKey}
Request Representation: StateDraft
Response Representation: State

Update State

Endpoint: /{projectKey}/states/{id}
Method: POST
OAuth2 Scopes: 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
Please find below the individual update actions provided on this endpoint.


Change state key

The key must be unique for all states.

  • action - String - "changeKey"
  • key - String

Set state name

Set state description

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 (e.g.: 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 - String - "setTransitions"
  • transitions - Array of Reference to State - Optional

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

Endpoint: /{projectKey}/states/{id}
Method: DELETE
OAuth2 Scopes: manage_orders:{projectKey}
Query Parameters:

  • version - Number - Required