Skip to main content

Generate billing documents for order line items and fulfillments

Zuora

Generate billing documents for order line items and fulfillments

This article introduces how to generate billing documents for order line items in the following scenarios:

  • When the order line item is without fulfillments, you can generate billing documents for the order line item.
  • When the order line item is with fulfillments, you can generate a billing document for each of the fulfillments.

For sales order line items, invoices are generated. For return order line items, credit memos are generated if you have enabled the Invoice Settlement feature; otherwise, negative invoices are generated.

Generate billing documents for order line items

After an order line item is created, its state is Executing by default. To generate billing documents for the order line item, you must change the state to SentToBilling. For more information about the state transition flow of an order line item, see State transitions for an order line item, fulfillment, and order.

To generate a billing document for an order line item, you can use one of the following ways:

  • Use the Zuora UI.

    Make sure the state of the order line item is SentToBilling and the bill target date is set appropriately. Then, create or schedule a bill run to generate the billing document. The bill run will pick up order line items based on the Bill Target Date. See Use the Zuora UI.

  • Use the REST API:
    • Update a single order line item 

      First, use the "Update an order line item" operation to update the state and the bill target date of the order line item appropriately. Then, use the "CRUD: Create a bill run" operation to create a bill run. See Update one order line item and then create a bill run.

    • Update multiple order line items in a single API

      Use the "Update order line items" operation to update both the state and billTargetDate fields of more than one order line item, as well as to generate an billing document for the referenced order line item using the single API. See Update multiple order line items and generate billing documents at the same time.

Use the Zuora UI

  1. Log in to the Zuora application and then navigate to Customers > Orders. The Orders page opens.
  2. Search for the order that contains the order line item to be updated and click the order number. The Order details page opens.
  3. In the Order Line Items area, on the target line of the order line item, click the pencil icon in the ACTIONS column. The Edit Order Line Item window is displayed.

  4. In the Basic Information section, change the Item State value from Executing to SentToBilling.
  5. (Optional): Update the Bill Target Date value if necessary. The subsequent bill run will pick up order line items to generate billing documents based on the bill target date.
  6. Click Save. The window is closed. The state of the order line item is changed to SentToBilling.
  7. To generate the billing document, create a bill run. For instructions, see Creating Bill Runs.

Use the REST API

There are two methods to update the order line item and generate billing documents.

Update one order line item and then create a bill run

To update a single order line item and then generate the billing document, use the Update an order line item operation.

  1. Determine the following values for the "Update an order line item" operation:
    • orderLineItemId: The ID of the order line item to be updated. You can obtain the order line item ID by using the Retrieve an order operation or from the URI of the Order Line Item Details page in the UI.
    • itemState: The state of the order line item. This field must be set to SentToBilling for the billing document to be generated.
    • billTargetDate: The date when the order line item is to be billed. The subsequent bill run will pick up order line items based on this date.
  2. Use the "Update an order line item" operation to update the order line item state and bill target date appropriately.

    The following API updates the state of an order line item to SentToBilling and sets the Bill Target Date for the order line item to 2021-02-01.

    Request PUT /v1/order-line-items/{orderLineItemId}
    Request Body
    {
       "itemState": "SentToBilling",
       "billTargetDate": "2021-02-01"
    }
  3. Use the "CRUD: Create a bill run" operation to create an ad hoc bill run.

Update multiple order line items and generate billing documents at the same time

To update order line items and generate the billing document at the same time, use the Update order line items operation.

  1. Determine the following values for the "Update order line items" operation:
    • orderLineItemId: The ID of the order line item to be updated. You can obtain the order line item ID by using the Retrieve an order operation or from the URI of the Order Line Item Details page in the UI.
    • itemState: The state of the order line item. This field must be set to SentToBilling for the billing document to be generated.
    • billTargetDate: The date when the order line item is to be billed. 
    • runBilling: Set this field in the processingOptions section to true to generate the billing document at the same time when you update the order line items.
  2. Use the "Update order line items" operation to update the order line items and generate the billing document.

    The following API provides an array of the order line item IDs to be updated and generates the billing document when updating the order line items. The state of all order line items is changed to SentToBilling and the bill target date is set to 2021-02-01. 

    Request POST /v1/order-line-items/bulk
    Request Body
    {
        "processingOptions": {
            "runBilling": true,
            "billingOptions": {
                "targetDate": "2021-01-01"
            }
        },
        "orderLineItems": [
            {
                "id": "{{orderLineItemId}}",
                "itemState": "SentToBilling",
                "billTargetDate": "2021-02-01"
            }
        ]
    }

Generate billing documents for fulfillments

After a fulfillment is created, its state is Executing by default. To generate billing documents for the fulfillment, you must change the state to SentToBilling. For more information about the state transition flow of a fulfillment, see State transitions for an order line item, fulfillment, and order.

To generate a billing document for a fulfillment, you can use one of the following ways:

  • Use the Zuora UI.

    Make sure the state of the fulfillment is SentToBilling and the bill target date is set appropriately. Then, create or schedule a bill run to generate the billing document. The bill run will pick up fulfillments based on the Bill Target Date. See Task 2: Add fulfillments to the sales order line item in Create a sales order line item with fulfillments.

  • Use the REST API.
    • Use the Create fulfillments operation to create fulfillments and set the processingOptions nested field properly to indicate that billing documents should be generated immediately when the fulfillments are created. To allow the generation of billing documents, make sure the state of the fulfillment is SentToBilling and the bill target date is set. See Task 2: Use the Create fulfillments operation in Create a sales order line item with fulfillments.
    • Use the Create fulfillments operation to create fulfillments but without using the processingOptions nested field to request the immediate generation of the billing documents. Then, when you are to generate billing documents for a fulfillment, use the CRUD: Create a bill run operation to create an ad hoc bill run. To allow the generation of billing documents, make sure the state of the fulfillment is SentToBilling and the bill target date is set. Use the Update a fulfillment operation to set the preceding fields if necessary.

The Fulfillment and Return feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at Zuora Global Support.