Skip to main content

Create a sales order line item with fulfillments

Zuora

Create a sales order line item with fulfillments

You can create a sales order line item for your non subscription based transactional charges, and then create fulfillments to track the shipment of the sales order line item. A fulfillment can be created to a sales order line item only when the billing rule of the order line item is configured as Trigger As Fulfillment Occursand the order line item is in the Booked state.

A sales order line item is managed in Zuora Billing as an order line item of the Sales item category. A fulfillment is a subordinate object created to an order line item. The maximum number of fulfillments that can be created to an order line item is 100.

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.

There are two ways to create a sales order line item with fulfillments:

  • In the Zuora UI, create an order, add a sales order line item to this order, and then add fulfillments to the order line item.
  • Use the Create an order API operation, and then use the Create fulfillments API operation.

Use the Zuora UI

To create a sales order line item with fulfillments from the UI, perform the following tasks:

  1. Create an order and add a sales order line item
  2. Add fulfillments to the sales order line item

The following sections describe each of the preceding tasks in detailed steps:

Task 1: Create an order and add a sales order line item

To create a sales order line item from the UI, complete the following steps:

  1. Log in to the Zuora application and then navigate to Customers > Orders. The Orders page opens.
  2. Click Create New Order at the top right. The Create New Order page opens.

  3. In the Order Overview area, enter the name of the account that owns the order in the Account field. By default, the account that owns the order will also own the order line item.

    You can enter the account by clicking either Account Name or Account Number, as follows:

    • If you click Account Name, type part of the account name in the Account field, and the filtered accounts can be dynamically listed for your selection.
    • If you click Account Number, type the complete account number.
  4. In the Order Date field, enter the order date you are to assign to the order. 

  5. The Order Category dropdown list has the New Sales option selected by default. The New Sales option indicates that this order is to contain sales order line items. 

  6. Add the sales order line item. You have two options as follows:

    To enter the information about the order line item directly, in the Sales Order Line Items area, click Add Order Line Item on the right. The Add Order Line Item window is displayed.

    Or alternatively, you can add an order line item from the product catalog. In the Sales Order Line Items area, click Choose Products on the right. The Search Product window is displayed. Identify a one-time charge you are to add as an order line item and click Add. The Add Order Line Item window is displayed.

  7. Provide detailed information about the order line item. If in the previous step, you choose to add the order line item from the product catalog, you can change detailed information about the order line item. 

    Section Field name Description
    Overview Item Name Required field. Name of the order line item. This name represents the name of the object that is sold and will typically be displayed on invoices, quotes, portals, and so on.
    Product Code The product code that is used as an identifier for the downstream system. This code is used to map the products in external systems such as the SKU in an external product catalog or a provisioning system.
    Item Type Required field. The category of the order line item. Valid values are Fee, Product, and Services.
    Transaction Start Date The date an order line item transaction starts. If it is not specified, the Order date will be used as the transaction start date.
    Transaction End Date The date an order line item transaction is completed. If it is not specified, the transaction start date will be used as the transaction end date. Also, the transaction end date should always equal or be later than the transaction start date.
    Item Category

    The category of an order line item. Valid values are Sales and Return. See the meaning of each option as follows:

    • Sales indicates the order line item is a sales order line item.
    • Return indicates the order line item is a return order line item.

    This field is not editable. It is automatically set to Sales if you select New Sales in Step 5 of Task 1: Create an order and add a sales order line item.

    Description A brief description of the order line item for reference.
    Item State

    State of the order line item. Valid values are Executing, Sent To Billing, Complete, Canceled, and Booked. By default, the starting state of an order line item is Executing. For more information, see State transitions for an order line item, fulfillment, and order.

    If you are to add fulfillments to an order line item, set the state of the order line item to Booked

    Bill Target Date

    The date when the order line item is invoiced. 

    If you are to add fulfillments to an order line item, you do not need to set the bill target date on the order line item. Instead, you need to set the bill target date on the fulfillment. See Step 3 of Task 2: Add fulfillments to the sales order line item.

    Billing Trigger Rule

    Required field. The billing trigger rule of the order line item. Valid values are Without Fulfillment and As Fulfillment Occurs. See the meaning of each option as follows:

    • The Without Fulfillment option indicates the following:
      • This order line item is without fulfillments.
      • The billing documents for the order line item are generated based on the order line item.
    • The As Fulfillment Occurs option indicates the following:
      • This order line item is with fulfillments.
      • The billing documents for the order line item are generated based on fulfillments.

    If you are to create fulfillments for the order line item, select As Fulfillment Occurs from the Billing Trigger Rule dropdown list. If you select Without Fulfillment, you cannot create fulfillments for the order line item. 

    Subscription Link

    The related subscription number. Use this field to link an order line item to a related subscription. For example, hardware items can be linked to their respective software subscriptions.

    Pricing List Price Per Unit The list price per unit at the time of transaction. This field is used for reporting purposes. The Amount Per Unit value is used to determine the charge amount for this order line item. If List Price Per Unit is not specified, Amount Per Unit will be used as the list price.
    UOM Unit of measure. The UOM is defined in Billing settings
    Discount Type Type of discount to apply to the price. Use this field to specify the inline discount type. Valid values are Fixed Amount, Percentage, or None.
    Discount Per Unit

    The discount per unit at the time of transaction. Use this field in accordance with the Discount Type field, in the following manner:

    • If the Discount Type field is set as Percentage, this field specifies the discount percentage for each unit of the order line item.
    • If the Discount Type field is set as Fixed Amount, this field specifies the discount amount on each unit of the order line item.
    Amount Per Unit Required field. The amount that is charged per unit excluding discounts. This field can contain tax for tax inclusive.
    Quantity Quantity of the order line item to be purchased. The charge amount will be calculated based on the specified Quantity and Amount Per Unit values. When this field is specified, each unit must be identical and you cannot modify a unit individually. To have a different unit, create another order line item.
    Tax Tax Mode Tax mode for the order line item pricing. Indicates whether the charge amount is tax inclusive or tax exclusive.
    Tax Code The tax code that is used to identify the appropriate tax rules and rates to apply to this order.
    Billing Sold To Contact

    The ID of a contact that belongs to the billing account of the order line item. Use this field to assign an existing account as the sold-to contact of an order line item.

    The Sold To Contact dropdown list has the Default Contact from Account option selected by default. The Default Contact from Account option indicates that the default sold-to account under the billing account of this order is set as the sold-to account of the order line item.

    Finance Revenue Recognition Rule Name of the applicable revenue recognition rule.
    Recognized Revenue Accounting Code The accounting code for recognized revenue.
    Deferred Revenue Accounting Code The accounting code for deferred revenue.
    Contract Asset Accounting Code The accounting code for contract assets.
    Contract Liability Accounting Code The accounting code for contract liability.
    Contract Recognized Revenue Accounting Code The accounting code for contract recognized revenue.
    Adjustment Liability Accounting Code The accounting code for adjustment liability.
    Adjustment Revenue Accounting Code The accounting code for adjustment revenue.
    Unbilled Receivables Accounting Code The accounting code for unbilled receivables.
    Exclude Item Booking from Revenue Specifies whether to exclude non-revenue related rate plan charges and order line items from syncing to Zuora Revenue. This field is only available if you have enabled Zuora Billing - Revenue Integration.
    Exclude Item Billing from Revenue Specifies whether to exclude non-revenue related invoice items, invoice item adjustments, credit memo items, and debit memo items from syncing to Zuora Revenue. This field is only available if you have enabled Zuora Billing - Revenue Integration.
    Additional Information The custom fields that are defined on the Order Line Item object.
  8. After you are finished, click Save. The Add Order Line Item window is closed.

  9. (Optional): Repeat Step 6 - 8 in Task 1: Create an order and add a sales order line item to create more sales order line items as you need in the current order. The maximum number of order line items allowable in an order is 100. Use the Actions link to either edit or delete an order line item after creation.

  10. Click Activate to activate the order. The orders details page opens. A sales order line item is successfully created and added to the order.

    You can now continue to perform Task 2 as follows to add fulfillments to the sales order line item.

Task 2: Add fulfillments to the sales order line item

To add fulfillments to a sales order line item from the UI, complete the following steps:

  1. In the Sales Order Line Item area of the order details page, click the item name of the sales order line item to which you are to add fulfillments. The order line item details page opens.

    SaleOrderLineItemArea.jpg

  2. Click Create Fulfillments at the top right. The Create Fulfillment page opens.
  3. Provide detailed information about the fulfillment you are to add.
    Section Field name Description
    Overview Fulfillment Type

    Type of a fulfillment. Valid values are Delivery and Return

    This field is automatically set to Delivery if you select New Sales in Step 5 of Task 1: Create an order and add a sales order line item.

    Quantity Remaining for Delivery The quantity that is remaining to deliver. This is a reference field that you cannot edit. This field indicates the quantity that you can still fulfill for the order line item. 
    Fulfillment Quantity Required field. The quantity you are to fulfill in this fulfillment. The quantity to fulfill cannot exceed the quantity that is remaining for delivery.
    Fulfillment Date Required field. The date you are to assign to a fulfillment.
    Carrier The carrier that you choose to fulfill the order line item. The carrier options can be configured in Billing SettingsFulfillment Settings. See Configure Fulfillment Settings.
    Tracking Number The tracking number of a fulfillment.
    State

    State of a fulfillment. Valid values are Executing, Sent To Billing, Complete, Canceled, and Booked. By default, the starting state of a fulfillment is Executing. For more information, see State transitions for an order line item, fulfillment, and order.

    Set the Item State field to Sent To Billing to generate billing documents for the fulfillment.

    Billing Target Date

    The date when the fulfillment is billed.

    Set the bill target date to generate billing documents for the fulfillment.

    Description A brief description of the fulfillment for reference.
    Fulfillment Integration Fulfillment System The fulfillment system. The fulfillment system options can be configured in Billing SettingsFulfillment Settings. See Configure Fulfillment Settings.
    Fulfillment Location The fulfillment location. The fulfillment location options can be configured in Billing SettingsFulfillment Settings. See Configure Fulfillment Settings.
    External ID The ID of the fulfillment in an external system.
  4. (Optional) To add fulfillment items to a fulfillment, perform the following steps:

     a. In the Fulfillment Items section, click Add Item to add a fulfillment item to the fulfillment.

     b. In the Item Identifier field, enter the identifier information you are to add for the fulfillment item.

     c. In the Description field, enter the description for the fulfillment item. 

     d. Click the save icon icon-save.png at the right end. A fulfillment item is now added to the fulfillment.

     f. Repeat Step a - d to add more fulfillment items as you need in the current fulfillment. The maximum number of fulfillment items allowable in a fulfillment is 100. For more information about the limits, see Order Line Items limitations.

    You cannot add fulfillment items to a fulfillment if the fulfillment is still in the Executing state.

  5. Click Save at the top right. The fulfillment details page opens. A fulfillment is now successfully created and added to the sales order line item.

  6. (Optional) To add more fulfillments for the sales order line item, click the left arrow icon at the top left to return to the order line item details page, and then repeat Step 2 - 5 in Task 2: Add fulfillments to the sales order line item. The maximum number of fulfillments allowable for an order line item is 100. For more information about the limits, see Order Line Items limitations.

  7. (Optional) To generate billing documents for the fulfillment in the Sent To Billing state, create a bill run. For instructions, see Creating Bill Runs.

Use the REST API

To create a sales order line item with fulfillments through the REST API, perform the following tasks:

  1. Task 1: Use the Create an order operation to create an order and add a sales order line item.
  2. Task 2: Use the Create fulfillments operation to add fulfillments for the sales order line item and generate invoices.

Task 1: Use the Create an order operation

Use the Create an order operation to create an order line item and add a sales order line item. Keep the following points in mind when you run the "Create an order" operation:

  • Determine the following fields and other required custom fields for the sales order line item. Note that the default value for the itemCategory field is Sales, therefore you do not need to set the field for a sales order line item.

    • itemName
    • itemType
    • listPricePerUnit
    • quantity
  • To allow creating fulfillments for the order line item, the itemState field must be set to Booked and the billingRule field must be set to TriggerAsFulfillmentOccurs. For more information, see State transitions for an order line item, fulfillment, and order.

The following API request creates a sales order line item for an existing customer account. 

Request POST /v1/orders
Request Body
{
  "existingAccountNumber": "AN_1660044119927",
  "orderDate": "2022-01-01",
  "description": "",
  "orderLineItems": [
    {
      "itemName": "LMS Device Fee",
      "itemType": "Product",
      "description": "webcam",
      "purchaseOrderNumber": "PO-12345678",
      "productCode": "P-0000001",
      "quantity": 10,
      "listPricePerUnit": 100,
      "transactionStartDate": "2022-01-01",
      "transactionEndDate": "2022-01-01",
      "soldTo": "4028fc828244a0ac018244dfc9a90bee",
      "itemState": "Booked",
      "billingRule": "TriggerAsFulfillmentOccurs"
    }
  ]
}

Task 2: Use the Create fulfillments operation

Use the Create fulfillments operation to add fulfillments for the sales order line item and generate invoices for the fulfillments. Keep the following points in mind when you run the "Create fulfillments" operation:

  • Determine the following fields and other required custom fields for the fulfillment:

    • fulfillmentDate
    • quantity
  • Use the state and billTargetDate fields to determine the fulfillments that are to be invoiced at the specified date. For a fulfillment to be invoiced, its state must be SentToBilling. When a bill run is created, it will pick up fulfillments to be invoiced based on the billTargetDate field.

  • Use the processingOptions nested field to indicate whether an invoice should be generated.

The following API request creates two fulfillments for the sales order line item created in the preceding task and also runs billing at the same time. 

Request POST /v1/fulfillments
Request Body
{
  "fulfillments": [
    {
      "fulfillmentDate": "2022-01-01",
      "quantity": 5,
      "description": "fulfillment batch 1",
      "state": "SentToBilling",
      "billTargetDate": "2022-01-01",
      "orderLineItemId": "4028828c82819b74018286e02e041bd6",
      "fulfillmentType": "Delivery",
      "trackingNumber": "T-0009872",
      "carrier": "CarrierA",
      "fulfillmentSystem": "SystemA",
      "fulfillmentLocation": "LocationA",
      "externalId": "SRC-0987123"
    },
    {
      "fulfillmentDate": "2022-01-02",
      "quantity": 5,
      "description": "fulfillment batch 2",
      "state": "SentToBilling",
      "billTargetDate": "2022-01-01",
      "orderLineItemId": "4028828c82819b74018286e02e041bd6",
      "fulfillmentType": "Delivery",
      "trackingNumber": "T-00098721",
      "carrier": "CarrierB",
      "fulfillmentSystem": "SystemB",
      "fulfillmentLocation": "LocationB",
      "externalId": "SRC-09871234"
    }
  ],
  "processingOptions": {
    "billingOptions": {
      "documentDate": "2022-01-02",
      "targetDate": "2022-01-02"
    },
    "runBilling": true
  }
}