State transitions for order line items, fulfillments, and orders

Last updated
Save as PDF

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

Order line items are introduced in Orders to facilitate launching non-subscription business models in Zuora. Order line items represent non subscription based transactional charges, such as one-time fees, physical goods, or professional service charges. Fulfillments are subordinate objects attached to an order line item to track the shipment or fulfillment of the order line item. To support a series of business processes, states are introduced on orders, order line items, and fulfillments. These states are used for the following purposes:

Identify where an object is in its lifecycle.
Determine what actions can be performed on an object of a certain state; for example, if an order line item is complete it cannot be canceled.

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

Executing
Booked
SentToBilling
Complete
Canceled

When the state of an order line item is set to Booked and the billing rule of the order line item is configured as Trigger As Fulfillment Occurs, fulfillments can be created and attached to an order line item. In this case, the state of an order line item can be one of the following:

Executing
Booked
Complete
Canceled

The state of a fulfillment can be one of the following:

Executing
Booked
SentToBilling
Complete
Canceled

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

Executing
Complete
Canceled

Note that regarding the Order object, the state field is not the same as the Status field. You can see the Status field in the Orders UI. For more information, see Order Status.

The following sections describe the state transitions of the order line item, fulfillment, and order object. The state transition for a sales order line item is the same as that of a return order line item. Also, the state transition of a fulfillment attached to a sales order line item is the same as that of a fulfillment attached to a return order line item.

State transitions for order line item without fulfillments

When the billing rule setting is configured as Trigger Without Fulfillment, an order line item is processed without fulfillments. The state transitions of an order line item without fulfillments are as shown in the following diagram:

Path 1: the default state Executing

As illustrated in Path 1 of the preceding diagram, 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.

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

When an order line item is in the Executing state, you can still update certain fields of this order line item, such as the price or quantity. Note that the fields you can update for a sales order line item are different than those for a return order line item. See the field descriptions of the Update an order line item operation to check the fields that you can update for an order line item of either category.

Your ERP system integrated with Zuora Billing can also update the fields on an order line item of the Executing state.

You cannot sync the information about an order line item of the Executing state to Zuora Revenue.

Path 2: from Executing to Booked

As illustrated in Path 2 of the preceding diagram, you can set an order line item to the Booked state when it is in the Executing state.

When an order line item is ready for fulfillment and revenue integration, you can set it to the Booked state.

You can trigger the state transition from Executing to Booked through either of the following ways:

Create an order line item through the Create an order operation and set the itemState field to Booked.
Create an order line item through the Orders UI and set the Item State field to Booked.
Update an order line item through the Update an order line item or Update order line items operation, and set the itemState field set to Booked.
Update an order line item through the Orders UI and set the Item State field set to Booked.

If an order line item is in the Booked state, you can update the paymentTerm, invoiceTemplateId, sequenceSetId, invoiceGroupNumber, and billTargetDate fields.

Path 3: from Booked to SentToBilling

As illustrated in Path 3 of the preceding diagram, you can set an order line item to the SentToBilling state when it is in the Booked state.

When an order line item is ready for invoicing, you can set it to the SentToBilling state. The SentToBilling state can be the terminal state and does not always move to the Complete state. You must set an order line item to the SentToBilling state if you want to generate billing docs for the order line item. Once an order line item is set to SentToBilling it cannot be canceled. For sales order line items, invoices are generated. For return order line items, negative invoices or credit memos are generated.

You can sync the information about an order line item of the SentToBilling state to Zuora Revenue.

You can trigger the state transition from Booked to SentToBilling through either of the following ways:

Update an order line item through the Update an order line item or Update order line items operation, and set the itemState field to SentToBilling.
Update an order line item through the Orders UI and set the Item State field set to SentToBilling.

If an order line item is in the SentToBilling state, you can update the paymentTerm, invoiceTemplateId, sequenceSetId, and invoiceGroupNumber fields.

The billTargetDate field must have a value before an order line item is set to the SentToBilling state.

See Generate invoice for order line items for a tutorial.

Path 4: from SentToBilling to Complete

As illustrated in Path 4 of the preceding diagram, you can set an order line item to the Complete state when it is in the SentToBilling state.

The state transition from SentToBilling to Complete is used when some post-billing installation is required before an order line item is complete.

The order line item of the Complete state is locked for any edits by any user.

You can sync the information about an order line item of the Complete state to Zuora Revenue.

You can trigger the state transition from SentToBilling to Complete through either of the following ways:

Update an order line item through the Update an order line item or Update order line items operation, and set the itemState field to Complete.
Update an order line item through the Orders UI and set the Item State field to Complete.

Path 5: from Executing to SentToBilling

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

The state transition from Executing to SentToBilling can be used for fees that do not require fulfillment.

The order line item of the SentToBilling state is locked for any edits by any user.

You can sync the information about an order line item of the SentToBilling state to Zuora Revenue.

You can trigger the state transition from Executing to SentToBilling through either of the following ways:

Create an order line item through the Create an order operation and set the itemState field to SentToBilling.
Create an order line item through the Orders UI and set the Item State field to SentToBilling.
Update an order line item through the Update an order line item or Update order line items operation, and set the itemState field to SentToBilling.
Update an order line item through the Orders UI and set the Item State field to SentToBilling.

See Generate invoice for order line items for a tutorial.

Path 6: from Executing to Complete

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

The state transition from Executing to Complete is used when fulfillment is skipped and billing is also skipped.

The order line item of the Complete state is locked for any edits by any user.

You can sync the information about an order line item of the Complete state to Zuora Revenue.

You can trigger the state transition from Executing to Complete through either of the following ways:

Create an order line item through the Create an order operation and set the itemState field to Complete.
Create an order line item through the Orders UI and set the Item State field to Complete.
Update an order line item through the Update an order line item or Update order line items operation and set the itemState field to Complete.
Update an order line item through the Orders UI and set the Item State field to Complete.

Path 7: from Executing to Canceled

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

The state transition from Executing to Canceled is used when an order or order line item is canceled while the order is in progress.

The order line item of the Canceled state is locked for any edits by any user.

You cannot sync the information about an order line item of the Canceled state to Zuora Revenue.

You can trigger the state transition from Executing to Canceled through either of the following ways:

Create an order line item through the Create an order operation and set the itemState field to Canceled.
Create an order line item through the Orders UI and set the Item State field to Canceled.
Update an order line item through the Update an order line item or Update order line items operation, and set the itemState field to Canceled.
Update an order line item through the Orders UI and set the Item State field to Canceled.

Path 8: from Booked to Complete

As illustrated in Path 8 of the preceding diagram, you can set an order line item to the Complete state when it is in the Booked state.

The state transition from Booked to Complete is used when billing is skipped but fulfillment is not skipped: for example, a welcome package or letter is fulfilled but no billing is required.

The order line item of the Complete state is locked for any edits by any user.

You can sync the information about an order line item of the Complete state to Zuora Revenue.

You can trigger the state transition from SentToBilling to Complete through either of the following ways:

Update an order line item through the Update an order line item or Update order line items operation, and set the itemState field to Complete.
Update an order line item through the Orders UI and set the Item State field to Complete.

State transitions for order line item with fulfillments

When the billing rule of an order line item is configured as Trigger As Fulfillment Occurs, the order line item can be processed with fulfillments. The state transitions of an order line item with fulfillments are as shown in the following diagram:

Path 1: the default state Executing

An order line item of the Executing state is not ready yet for being sent to fulfillment. When an order line item is in the Executing state, you can still update certain fields of this order line item, such as the price or quantity. Note that the fields you can update for a sales order line item are different than those for a return order line item. See the field descriptions of the Update an order line item operation to check the fields that you can update for an order line item of either category.

Your ERP system integrated with Zuora Billing can also update the fields on an order line item of the Executing state.

You cannot sync the information about an order line item of the Executing state to Zuora Revenue.

Path 2: from Executing to Booked

As illustrated in Path 2 of the preceding diagram, you can set an order line item to the Booked state when it is in the Executing state.

When an order line item is ready for fulfillment and revenue integration, you can set it to the Booked state.

You can trigger the state transition from Executing to Booked through either of the following ways:

Create an order line item through the Create an order operation and set the itemState field to Booked.
Create an order line item through the Orders UI and set the Item State field to Booked.
Update an order line item through the Update an order line item or Update order line items operation, and set the itemState field set to Booked.
Update an order line item through the Orders UI and set the Item State field to Booked.

If an order line item is in the Booked state, you can update the paymentTerm, invoiceTemplateId, sequenceSetId, invoiceGroupNumber, and billTargetDate fields.

Path 3: from Booked to Complete

As illustrated in Path 3 of the preceding diagram, when all fulfillments attached to an order line item are completed, the system will automatically move the Booked state of an order line item to the Complete state. This state transition cannot be performed by any user. Note that a fulfillment is treated as completed when it is in the SentToBilling or Complete state.

The order line item of the Complete state is locked for any edits by any user.

You can sync the information about an order line item of the Complete state to Zuora Revenue.

Path 4: from Executing to Canceled

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

The state transition from Executing to Canceled is used when an order or order line item is canceled while the order is in progress.

The order line item of the Canceled state is locked for any edits by any user.

You cannot sync the information about an order line item of the Canceled state to Zuora Revenue.

You can trigger the state transition from Executing to Canceled through either of the following ways:

Create an order line item through the Create an order operation and set the itemState field to Canceled.
Create an order line item through the Orders UI and set the Item State field to Canceled.
Update an order line item through the Update an order line item or Update order line items operation, and set the itemState field to Canceled.
Update an order line item through the Orders UI and set the Item State field to Canceled.

State transitions for fulfillment

When the billing rule setting for an order line item is configured as Trigger As Fulfillment Occurs, fulfillments can be created and attached to the order line item. The state transition of a fulfillment is shown in the following diagram. Note that you cannot skip the SentToBilling state when the fulfillment is in the Executing or Booked state. Skip of billing is not allowed due to the billing rule.

Path 1: the default state Executing

As illustrated in Path 1 of the preceding diagram, when a fulfillment is created, its default state is Executing, unless you directly set the state of a fulfillment to the SentToBilling state through the Fulfillment UI or API.

The Executing state is used when a fulfillment is in progress, for example, when a fulfillment record is created in Zuora as a placeholder. This is an optional step in the fulfillment processing procedure.

When a fulfillment is in the Executing state, you can still update certain fields of this fulfillment, such as the quantity. See the description of the “Update a fulfillment” operation to check the fields that you can update.

Your ERP system integrated with Zuora Billing can also update the fields on a fulfillment of the Executing state.

Path 2: from Executing to Booked

As illustrated in Path 2 of the preceding diagram, you can set a fulfillment to the Booked state when it is in the Executing state.

When a fulfillment is ready for fulfillment and revenue integration, you can set it to the Booked state. The fulfillment is now locked for any edits. The Booked state is an optional step in the fulfillment processing procedure.

You can trigger the state transition from Executing to Booked through either of the following ways:

Create a fulfillment through the “Create fulfillments” operation and set the state field to Booked.
Create a fulfillment through the Fulfillment UI and set the State field to Booked.
Update a fulfillment through the “Update a fulfillment” operation, and set the state field set to Booked.
Update a fulfillment through the Fulfillment UI and set the State field to Booked.

Path 3: from Booked to SentToBilling

As illustrated in Path 3 of the preceding diagram, you can set a fulfillment to the SentToBilling state when it is in the Booked state.

The SentToBilling state is used when a fulfillment is ready for invoicing, for example, when sales order line items have been shipped or when return order line items have been received and approved at the warehouse. The SentToBilling state can be the terminal state and does not always move to the Complete state.

You must set a fulfillment to the SentToBilling state if you want to generate billing docs for fulfillment. Once a fulfillment is set to SentToBilling it cannot be canceled. If the fulfillment is for a sales order line item, an invoice item is generated. If the fulfillment is for a return order line item, a negative invoice item or credit memo is generated.

The fulfillment of the SentToBilling state is locked for any edits by any user.

You can trigger the state transition from Booked to SentToBilling through either of the following ways:

Update a fulfillment through the “Update a fulfillment” operation, and set the state field to SentToBilling.
Update a fulfillment through the Fulfillment UI and set the State field to SentToBilling.

See Generate invoice for order line items for a tutorial.

Path 4: from SentToBilling to Complete

As illustrated in Path 4 of the preceding diagram, you can set a fulfillment to the Complete state when it is in the SentToBilling state.

The state transition from SentToBilling to Complete is used when some post-billing installation is required before a fulfillment is complete, for example, when shipment notification is sent or when installation appointment is scheduled.

The fulfillment of the Complete state is locked for any edits by any user.

You can trigger the state transition from SentToBilling to Complete through either of the following ways:

Update a fulfillment through the “Update a fulfillment” operation, and set the state field to Complete.
Update a fulfillment through the Orders UI and set the State field to Complete.

Path 5: from Executing to SentToBilling

As illustrated in Path 5 of the preceding diagram, you can set a fulfillment to the SentToBilling state when it is in the Executing state.

The SentToBilling state is used when a fulfillment is ready for invoicing, for example, when sales order line items have been shipped or when return order line items have been received and approved at warehouse. The SentToBilling state can be the terminal state and does not always move to the Complete state.

You must set a fulfillment to the SentToBilling state if you want to generate billing docs for a fulfillment. Once a fulfillment is set to SentToBilling it cannot be canceled. If the fulfillment is for a sales order line item, an invoice item is generated. If the fulfillment is for a return order line item, a negative invoice item or credit memo is generated.

The fulfillment of the SentToBilling state is locked for any edits by any user.

You can trigger the state transition from Executing to SentToBilling through either of the following ways:

Update a fulfillment through the “Update a fulfillment” operation, and set the state field to SentToBilling.
Update a fulfillment through the Fulfillment UI and set the State field to SentToBilling.

See Generate invoice for order line items for a tutorial.

Path 6: from Executing to Canceled

As illustrated in Path 6 of the preceding diagram, you can set a fulfillment to the Canceled state when it is in the Executing state.

The state transition from Executing to Canceled for a fulfillment is used when the fulfillment is canceled while it is still in progress.

The fulfillment of the Canceled state is locked for any edits by any user.

You can trigger the state transition from Executing to Canceled through either of the following ways:

Update a fulfillment through the “Update a fulfillment” operation, and set the state field to Canceled.
Update a fulfillment through the Fulfillment UI and set the State field to Canceled.

Path 7: started as SentToBilling

As illustrated in Path 7 of the preceding diagram, you can create a fulfillment of the SentToBilling state directly.

The SentToBilling state is used when a fulfillment is ready for invoicing, for example, when sales order line items have been shipped or when return order line items have been received and approved at warehouse. The SentToBilling state can be the terminal state and does not always move to the Complete state.

The fulfillment of the SentToBilling state is locked for any edits by any user.

You can create a fulfillment of the SentToBilling state through either of the following ways:

Create a fulfillment through the “Create fulfillments” operation, and set the state field to SentToBilling.
Create a fulfillment through the Fulfillment UI and set the State field to SentToBilling.

State transitions for order

This section describes the state transitions for an order.

The following diagram illustrates the state transitions 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 that are not pending
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 Complete 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.

In 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. See Order Status.

Note that the field you can see in the Orders UI is the Status field, not the state field.

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 Draft, the order is in the Executing state.
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.