Skip to main content

Overview of Order Line Items

Zuora

Overview of Order Line Items

This article introduces the Order Line Items feature.

What are Order Line Items?

Order Line Items are objects contained in an Order object to represent non-subscription based charges. With order line items, you can use the Orders API and UI to send non-subscription based transactional charges, such as one-time fees, physical goods, or professional service charges, from quoting through revenue recognition, without the need for a subscription. You can also manage the entire lifecycle of your non-subscription based business through order line items.

Benefits of using Order Line Items

Previously, when charging for non-subscription-based goods and services, you had to use different ways to add non-subscription based charges to the end subscriber’s account, including the following: 

  • Create a new subscription or amend an existing subscription each time when a product is sold, with the following inconvenience: 
    • Not an accurate representation of your customer
    • API and UI performance degradation after too many new subscriptions
    • Difficult to manage the actual subscription
  • Use usage charges to capture the purchase and pass the usage in at some point after the purchase, with the following inconvenience:
    • Complicated solution
    • Might not accurately validate funds before service is provided
    • Billing and payment timing options are not ideal
  • Hold non-subscription based charges in another system out of Zuora, with the following inconvenience:
    • Billing, reporting, and revenue out of multiple systems
    • More complex integrations

Compared with the preceding ways, you can now use order line items to create and manage your non-subscription based transactional charges with the following benefits:

  • Create an ad-hoc one-time charge without pre-defining it in the product catalog
  • Manage non-subscription based charges directly instead of having to manage them through subscriptions
  • Apply discounts on non-subscription based charges immediately through inline discounts supported in order line items without depending on the discount charges in the product catalog
  • Set a sold-to contact for each individual non-subscription based charge to resolve the limitation that only one sold-to contact is supported under an invoice owner account
  • Manage the entire business lifecycle of a non-subscription based charge, including the sales, shipment, and possibly return of a professional service or a piece of physical goods
  • Mange the billing target dates based on the fulfillment status of physical goods or services to support near real-time billing for your business
  • Manage both your non-subscription based transactional charges and recurring charges within Zuora Billing

Functions provided by Order Line Items

With order line items, you can use the Orders UI and API to create and use objects in the following ways to support your unified monetization business model:

  • One or more subscriptions
  • One or more order line items
  • Or a hybrid order containing both subscriptions and order line items

You can manage the entire order line item lifecycle for businesses through order line item categories and fulfillments, as follows:

  • You can create order line items of both sales and return categories to track product sales and return. Also, you can generate billing documents based on the order line items accordingly, including invoices, negative invoices, and credit memos.
  • You can create and attach fulfillments to an order line item to track the shipment or return status. You can trigger billing based on the fulfillment state and generate billing documents based on the fulfillments accordingly as well. In addition, you can create and attach fulfillment items to a fulfillment to keep track of all the assets in your system.

As shown in the diagram below, order line items are stored outside of a subscription, and therefore do not require an amendment or order action, and do not impact the subscription version.

Fulfillments are subordinate objects attached to their related order line item. Fulfillment items are subordinate objects attached to their related fulfillment.

order-line-item-with-fulfillment.png

Even though order line items are stored outside of a subscription, order line item charges can be sent through the entire order to revenue process, including Invoicing, Payments, Collections, and Revenue.

To enable the ability to perform a series of business processes, states are introduced on Orders, Order Line Items, and Fulfillments. You can use the Order Line Items API, Fulfillments API, Orders API, and Orders UI to manage changes and state transitions. For more information, see State transitions for an order, order line item, and fulfillment.

Discounts are supported on order line items through inline discounts. See Inline discounts for order line items.

Query order line items

You can query order line items by the following ways:

You can query fulfillments and fulfillment items in the following ways:

Limitations

  • The maximum number of order line items allowed in a Create an order operation is 100.
  • The maximum number of order line items allowed in a Create an order asynchronously operation is 100.
  • The maximum number of order line items allowed in an Update order line items operation is 100.
  • The maximum number of fulfillments allowed in an order line item is 100. If you need to increase the limit, contact Zuora Global Support to validate your business case.
  • The maximum number of fulfillment items allowed in a fulfillment is 100. If you need to increase the limit, contact Zuora Global Support to validate your business case.
  • Order line items support only Flat Fee and Per Unit charge models of the one-time charge type. 
  • Negative values for quantity are not supported for order line items.

Limitations for interaction with Invoice Settlement

Generally, invoices with a negative total amount cannot be generated when the Invoice Settlement feature is enabled. However, when the Invoice Settlement feature is disabled, such invoices can be successfully generated.

The following tables demonstrate this limitation with examples, and the examples are grouped by different values of an invoice consolidation billing rule, that is, Allow to consolidate subscriptions, order line items and standalone invoice items into a single invoice.

  • When the Invoice Settlement feature is enabled and the invoice consolidation billing rule is set to Yes, no invoice or credit memo is generated with a negative total amount that includes the amount of the order line items. Examples 1 to 3 in Table 1 demonstrate this limitation; However, an invoice with a positive total amount can be successfully generated. See Examples 4 and 5 in Table 1.
    Table 1: Invoice Settlement is enabled, and the invoice consolidation billing rule is set to Yes

    Example

    Total amount of Sales Order Line Items

    Total amount of subscription charges

    Total amount

    Billing document generation

    Example 1 

    -$10

    n/a

    -$10

    No invoice or credit memo is generated. Billing document generation is rejected because of the negative total amount.

    Example 2

    -$30

    $20

    -$10

    No invoice or credit memo is generated. Billing document generation is rejected because of the negative total amount.

    Example 3 $30 -$100 -$70

    No invoice or credit memo is generated. Billing document generation is rejected because of the negative total amount.

    Example 4

    -$30

    $100

    $70

    A $70 invoice is generated.

    Example 5 $30 -$10 $20 A $20 invoice is generated.
  • When the Invoice Settlement feature is enabled and the invoice consolidation billing rule is set to No, no invoice or credit memo can be generated with a negative total amount of the order line items. Examples 1 to 3 in Table 2 demonstrate this limitation; However, an invoice with a positive total amount of the order line items can be successfully generated. See Examples 4 and 5 in Table 2. 
    Table 2: Invoice Settlement is enabled, and the invoice consolidation billing rule is set to No

    Example

    Total amount of Sales Order Line Items 

    Total amount of subscription charges

    Total amount

    Billing document generation

    Example 1 

    -$10

    n/a

    -$10

    No invoice or credit memo is generated. Billing document generation is rejected because of the negative total amount of order line items.

    Example 2

    -$30

    $20

    -$10

    • No invoice or credit memo is generated for the order line items. Billing document generation is rejected because of the negative total amount of order line items.
    • A $20 invoice is generated for the subscription charges.

    Example 3

    -$30

    $100

    $70

    • No invoice or credit memo is generated for the order line items. Billing document generation is rejected because of the negative total amount of order line items.
    • A $100 invoice is generated for the subscription charges.
    Example 4

    $30

    -$100

    -$70

    • A $30 invoice is generated for the order line items.
    • A $100 credit memo is generated for the subscription charges.
    Example 5

    $30

    -$10

    $20

    • A $30 invoice is generated for the order line items.
    • A $10 credit memo is generated for the subscription charges.

How to get started

You need to make sure you have access to the Order Line Items feature. The Order Line Items feature is now generally available. You need to enable the Orders or Orders Harmonization feature to access the Order Line Items feature.