State-based quantity calculations for order line items and fulfillments
Zuora calculates the quantities for order line items and fulfillments based on their states. For more information about states, see State transitions for an order line item, fulfillment, and order.
This article describes how Zuora calculates quantities for order line items and fulfillments based on their states with examples.
General rules for quantity calculations
The general rules are as follows:
- The quantity of order line items or fulfillments is the sum of the values of the
quantityPendingFulfillmentandquantityFulfilledfields. - The following states of the order line items or of their fulfillments trigger the quantity change in the
quantityPendingFulfillmentandquantityFulfilledfields of the order line items:- Booked
- SentToBilling (if the Booked state has been skipped)
- Complete (if the Booked state has been skipped)
- The SentToBilling state of the sales order line item or of their fulfillments triggers the quantity change in the
quantityAvailableForReturnfield of the sales order line item. - The following states of the return order line items or of their fulfillments trigger the quantity change in the
quantityAvailableForReturnfield of the associated sales order line item:- Booked
- SentToBilling (if the Booked state has been skipped)
- Complete (if the Booked state has been skipped)
The calculation logic differs slightly in the following types of order line items:
- Sales order line item without fulfillments
- Sales order line item with fulfillments
- Return order line item without fulfillments
- Return order line item with fulfillments
Sales order line item without fulfillments
The initial quantity of the sales order line item is 100. The initial state of the sales order line item is Executing. For sales order line item without fulfillments, you can learn the calculation logic from the following examples.
Example 1: Sales order line item without fulfillments is changed from Executing state to Booked state and then to SentToBilling or Complete state
If the state is changed from the Executing to Booked state, Zuora recognizes that the sales order line item is fully fulfilled without items pending to be fulfilled. Therefore, Zuora calculates the value of the quantityFulfilled field as 100 and the value of thequantityPendingFulfillment field as 0.
| Sales order line item without fulfillments | From Executing state | To Booked state |
|---|---|---|
| quantity | 100 | 100 |
| quantityPendingFulfillment | 0 | 0 |
| quantityFulfilled | 0 | 100 |
| quantityAvailableForReturn | 0 | 0 |
Then, if the state is changed from Booked to SentToBilling or Complete, Zuora recognizes that the sales order line is completed (including invoicing-related setups) and all items are ready and can be returned. Therefore, Zuora calculates the value of thequantityAvailableForReturn field as 100.
| Sales order line item without fulfillments | From Booked state | To SentToBilling or Complete state |
|---|---|---|
| quantity | 100 | 100 |
| quantityPendingFulfillment | 0 | 0 |
| quantityFulfilled | 100 | 100 |
| quantityAvailableForReturn | 0 | 100 |
Example 2: Sales order line item without fulfillments is changed from Executing state directly to SentToBilling or Complete state
If the state is directly changed from the Executing to the SentToBilling or Complete state, Zuora will presume that the order line item has passed the Booked state. In this case, Zuora recognizes that the sales order line item is fully fulfilled. Also, Zuora recognizes that the sales order line item is completed (including invoicing-related setups) and ready can be returned. Zuora calculates the value of the quantityFulfilled field as 100 and the value of thequantityPendingFulfillment field as 0. Simultaneously, Zuora calculates the value of thequantityAvailableForReturn field as 100.
| Sales order line item without fulfillments | From Executing state | To SentToBilling or Complete state |
|---|---|---|
| quantity | 100 | 100 |
| quantityPendingFulfillment | 0 | 0 |
| quantityFulfilled | 0 | 100 |
| quantityAvailableForReturn | 0 | 100 |
Sales order line item with fulfillments
Zuora calculates the value of the quantityPendingFulfillment, quantityFulfilled, and quantityAvailableForReturn fields based on the sum of the fulfillments that are changed to the Booked state or a later state. In the latter case, Zuora will presume that the fulfillments have passed the Booked state.
Example: sales order line item with two fulfillments in different states
The initial quantity of the sales order line item is 100 and the state of the sales order line item is Booked.
If there is a fulfillment (Fulfillment 1) with the quantity of 10 and state of Booked, Zuora recognizes the quantity of the booked fulfillment is the fulfilled quantity for the sales order line item. Therefore, Zuora calculates the value of thequantityFulfilled field of the sales order line item as 10 and the value of thequantityPendingFulfillment field as 90.
| Sales order line item with fulfillments | State and quantity | Fulfillment 1 | State and quantity |
|---|---|---|---|
| state | Booked | state | Booked |
| quantity | 100 | ||
| quantityPendingFulfillment | 90 | ||
| quantityFulfilled | 10 | quantity | 10 |
| quantityAvailableForReturn | 0 |
Then if the state of the fulfillment is changed from Booked to SentToBilling or Complete, Zuora recognizes that the fulfillment of the sales order line item is completed and is ready can be returned. Zuora calculates the value of thequantityAvailableForReturn field of the sales order line item as 10.
| Sales order line item with fulfillments | State and quantity | Fulfillment 1 | State and quantity |
|---|---|---|---|
| state | Booked | state | SentToBilling or Complete |
| quantity | 100 | ||
| quantityPendingFulfillment | 90 | ||
| quantityFulfilled | 10 | ||
| quantityAvailableForReturn | 10 | quantity | 10 |
After that, if there is another fulfillment (Fulfillment 2) with the quantity of 90 directly changed from Executing to the SentToBilling or Complete state, Zuora adds the quantity of the fulfillment with the previous one. Therefore, Zuora calculates the value of thequantityFulfilled field of the sales order line item as 100 and the value of the quantityPendingFulfillment field of the sales order line item as 0. Zuora also calculates the value of the quantityAvailableForReturn field of the sales order line item as 100.
When all fulfillments of the sales order line item are changed to SentToBilling, Complete, or Canceled state and the value of thequantityPendingFulfillment field of the sales order line item becomes 0, the sales order line item automatically changes from Booked to Complete.
| Sales order line item with fulfillments | State and quantity | Fulfillment 1 | State and quantity | Fulfillment 2 | State and quantity |
|---|---|---|---|---|---|
| state | Complete | state | SentToBilling or Complete | state | SentToBilling or Complete state (skipped Booked state) |
| quantity | 100 | ||||
| quantityPendingFulfillment | 0 | ||||
| quantityFulfilled | 100 | quantity | 10 | quantity | 90 |
| quantityAvailableForReturn | 100 |
Return order line item without fulfillments
Zuora calculates the values of thequantityPendingFulfillment and quantityFulfilled fields of the return order line item without fulfillments in a similar way to the sales order line item without fulfillments.
Example: return order line item without fulfillments is changed from Executing state to Booked, SentToBilling, or Complete state
The initial quantity of the sales order line item is 100 and the state of the sales order line item is SentToBilling or Complete. The quantity of the associated return order line item is 40 and the initial state of the return order line item is Executing.
If the state is changed from the Executing to Booked state or a later state, Zuora recognizes that the return order line is fully fulfilled without items pending to be fulfilled. Therefore, Zuora calculates the value of the quantityFulfilled field of the return order line item as 40 and the value of the quantityPendingFulfillment field of the return order line item as 0.
The quantity of the returned order line item in the Booked state or a later state affects the value of thequantityAvailableForReturn field of the associated sales order line item. If the initial quantity of the sales order line item is 100, then Zuora calculates the value of the quantityAvailableForReturn field of the sales order line item as 60 by subtracting the value of thequantityfield of the return order line item from the value of thequantityfield of the sales order line item.
| sales order line item | State and quantity | Associated return order line item without fulfillments | State and quantity |
|---|---|---|---|
| state | SentToBilling or Complete | state |
The state is one of the following:
|
| quantity | 100 | quantity | 40 |
| quantityPendingFulfillment | 0 | quantityPendingFulfillment | 0 |
| quantityFulfilled | 100 | quantityFulfilled | 40 |
| quantityAvailableForReturn | 60 |
Return order line item with fulfillments
Zuora calculates the values of thequantityPendingFulfillment and quantityFulfilled fields of the return order line item with fulfillments in a similar way to the sales order line item with fulfillments.
Zuora calculates the values of thequantityPendingFulfillment and quantityFulfilled fields of the return order line item based on the sum of the fulfillments of the return order line item that are changed to the Booked state or a later state. In the latter case, Zuora will presume that the fulfillments have passed the Booked state. However, Zuora calculates the value of the quantityAvailableForReturnfield of the sales order line item still based on the return order line item that is changed to the Booked state or a later state.
Example: return order line item with two fulfillments in different states
The initial quantity of the sales order line item is 100 and the state of the sales order line item is SentToBilling or Complete. The quantity of the associated return order line item is 40 and the state of the return order line item is Booked.
If there is a fulfillment (Fulfillment 1) with the quantity of 10 and state of Booked, Zuora recognizes the quantity of the booked fulfillment is the fulfilled quantity for the return order line item. Therefore, Zuora calculates the value of thequantityFulfilled field of the return order line item as 10 and the value of thequantityPendingFulfillment field as 30. The quantity of the return order line item in the Booked state or a later state affects the value of thequantityAvailableForReturn field of the associated sales order line item. Zuora calculates the value of thequantityAvailableForReturn field of the sales order line item as 60 by subtracting the value of thequantity field of the return order line item from the value of thequantity field of the sales order line item.
| Sales order line item | State and quantity | Associated return order line item | State and quantity | Fulfillment 1 | State and quantity |
|---|---|---|---|---|---|
| state | SentToBilling or Complete | state | Booked | state | Booked |
| quantity | 100 | quantity | 40 | ||
| quantityPendingFulfillment | 0 | quantityPendingFulfillment | 30 | ||
| quantityFulfilled | 100 | quantityFulfilled | 10 | quantity | 10 |
| quantityAvailableForReturn | 60 |
After that, if there is another fulfillment (Fulfillment 2) with the quantity of 10 that is directly changed from Executing to the SentToBilling or Complete state, Zuora adds the quantity of the fulfillment with the previously booked one. Therefore, Zuora calculates the value of the quantityFulfilled field of the return order line item as 20 and the value of the quantityPendingFulfillment field as 20.
| Sales order line item | State and quantity | Associated return order line item | State and quantity | Fulfillment 1 | State and quantity | Fulfillment 2 | State and quantity |
|---|---|---|---|---|---|---|---|
| state | SentToBilling or Complete | state | Booked | state | Booked | state | SentToBilling or Complete |
| quantity | 100 | quantity | 40 | ||||
| quantityPendingFulfillment | 0 | quantityPendingFulfillment | 20 | ||||
| quantityFulfilled | 100 | quantityFulfilled | 20 | quantity | 10 | quantity | 10 |
| quantityAvailableForReturn | 60 |
When all fulfillments of the return order line item are changed to SentToBilling, Complete, or Canceled state and the value of the quantityPendingFulfillment field of the return order line item becomes 0, the return order line item automatically changes from Booked to Complete. However, in this example, the return order line item will not change to Complete because the value of the quantityPendingFulfillment field is still 20.