Skip to main content

Order line item states, order states, and state transitions

Zuora

Order line item states, order states, and state transitions

This article describes the states of an order line item, the states of an order, and the state transitions.

Order line items are introduced in Orders to facilitate launching non-subscription business models in Zuora. To enable the ability to perform a series of business processes, states are introduced on both orders and order line items.

The states of an order line item are used to:

  • Identify where an order line item is in its lifecycle.
  • Define what actions can be performed on an order or order line item, for example, if an order line item is complete it cannot be canceled. 

Also, state is not the same as status. Status is a custom description used for reporting by the customer.

The state of an order line item can be one of the following:

  • Executing
  • SentToBilling
  • Complete
  • Canceled

The state of an order can be one of the following:

  • Executing
  • Complete
  • Canceled 

Order line item state transition

This section describes the state transition of an order line item and how to trigger the state transition. 

The following diagram illustrates the state transition of an order line item.

Order Line Item Graphics - OLI-state-with-order.jpeg

Path 1: the default state Executing

As illustrated in Path 1 of the diagram above, when an order line item is created, its default state is Executing, unless you directly set the state of an order line item to another state through the Orders UI or API when creating the order line item.

The Executing state is used to represent standard processing that an order line item may go through such as shipping, provisioning, or manual tasks. These lower-level descriptions can be captured through custom fields or status.

Path 2: from Executing to SentToBilling

As illustrated in Path 2 of the diagram above, you can set an order line item to the SentToBilling state when it is in the Executing state. You must set an order line item to the SentToBilling state if you want to generate invoice for the order line item. Currently, once an order line item is set to SentToBilling it cannot be canceled.

You can trigger this state transition through either of the following ways:

  • Creating an order line item through the Create an order operation with the itemState field set to SentToBilling.
  • Creating an order line item through the Orders UI with the itemState field set to SentToBilling.
  • Updating an order line item through the Update an order line item or Update order line items operation, with the itemState field set to SentToBilling
  • Updating an order line item through the Orders UI with the itemState field set to SentToBilling

See Generate invoice for order line items for a tutorial.

Path 3: from SentToBilling to Complete

As illustrated in Path 3 of the diagram above, you can set an order line item to the Complete state when it is in the SentToBilling state. Currently, once an order line item is complete it can no longer be updated.

You can trigger this state transition through either of the following ways:

  • Updating an order line item through the Update an order line item or Update order line items operation, with the itemState field set to Complete
  • Updating an order line item through the Orders UI with the itemState field set to Complete

Path 4: from Executing to Canceled

As illustrated in Path 4 of the diagram above, you can set an order line item to the Canceled state when it is in the Executing state.

You can trigger this state transition through either of the following ways:

  • Creating an order line item through the Create an order API with the itemState field set to Canceled.
  • Creating an order line item through the Orders UI with the itemState field set to Canceled.
  • Updating an order line item through the Update an order line item or Update order line items operation, with the itemState field set to Canceled
  • Updating an order line item through the Orders UI with the itemState field set to Canceled

Path 5: from Executing to Complete

As illustrated in Path 5 of the diagram above, you can directly set an order line item to the Complete state when it is in the Executing state.

You can trigger this state transition through either of the following ways:

  • Creating an order line item through the Create an order API with the itemState field set to Complete.
  • Creating an order line item through the Orders UI with the itemState field set to Complete.
  • Updating an order line item through the Update an order line item or Update order line items operation, with the itemState field set to Complete
  • Updating an order line item through the Orders UI with the itemState field set to Complete

Order state transition

This section describes the state transition for orders.

The following diagram illustrates the state transition of an order.

Order State Machine and Orchestration - Order State Machine.jpeg

When an order is submitted, the order state becomes Executing, which will:

  • Execute all order actions
  • Put all order line items to the Executing state (unless another State is specified for the order line item in theitemStatefield in the Orders UI or API)

An order is Completed only when:

  • All order actions are executed (activated)
  • And all order line items are complete

An order is Canceled when:

  • No subscription (or order action) is in it
  • And if all order items are Canceled.

As a summary, the state of an order is determined by two sets of factors:

  • State of each of the order line items within the order
  • Status of the order itself - The status of an order can be either Pending or Completed. See what determines the status of an order in Pending order and subscription.

The following sections describe the order state in different scenarios.

When only order line items are present in the order

When only order line items are present in the order, the order state is as below:

  • When any order line item in the order is in the Executing state, the order is in the Executing state.
  • When any order line item in the order is in the SentToBilling state, the order is in the Executing state.
  • When all order line items in the order are in the Complete state, the order is in the Complete state.
  • When all order line items in the order are in the Canceled state, the order is in the Canceled state.
  • When some order line items in the order are in the Complete state and the other order line items are in the Canceled state, the order is in the Complete state.

When only subscriptions are present in the order

When only subscriptions are present in the order, the order state is determined by the status of the order.

  • When the status of the order is Pending, the order is in the Executing state.
  • When the status of the order is Completed, the order is in the Complete state.

When both order line items and subscriptions are present in the order

When both order line item and subscription are present in the order, the order state can be either Executing or Complete.

  • When the order status is Pending, the order state is Executing.
  • When any of the order line items in the order is in the Executing or SentToBilling state, the order is the Executing state.
  • When all of the order line items in the order are in the Complete state and the order status is Completed, the order is in the Complete state.
  • When all of the order line items in the order are in the Canceled state and the order status is Completed, the order is in the Complete state.
  • When some of the order line items in the order are in the Complete state, the other of the order line items in the order are in the Canceled state, and the order status is Completed, the order is in the Complete state.