Skip to main content

Create a return order line item with fulfillments

Zuora

Create a return order line item with fulfillments

You can create multiple return order line items when you want to return one existing sales order line item. You can also create fulfillments (no more than 100) and fulfillment items on the return order line item to return your items.

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.

Prerequisites

You can return a sales order line item that has been fully delivered or partially delivered. The sales order line item that has been fully delivered can be identified by its  SentToBilling, or Complete state. The sales order line item that has been partially delivered can be a sales order line item in the Booked state with its fulfillments in either SentToBilling or Complete state. In these cases, the quantityAvailableForReturn field in the REST API or Available to Return field in the UI of the sales order line item has a positive value, which indicates there are items that can be returned. For information about the states, see State transitions for an order line item, fulfillment, and order.

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

Use the Zuora UI

In the Zuora UI, you can create a return order line item through either of the following ways:

  • Create an order and add a return order line item to this order.
  • Create a return order line item from an existing order details page.

Create an order and add a return order line item

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. This must be the order account that owns the sales order line item you are to return. 

    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. From the Order Category dropdown list, select Return. Then, you can see the following options are displayed for the return order line item:

    • the Reason Code dropdown list 

    • the Return Order Line Items area

  6. (Optional): From the Reason Code dropdown list, select a reason code to indicate the reason for your product return. Options on the Reason Code dropdown list can be configured in Billing Settings > Configure Reason Codes. For more information, see Configure Reason Codes.

  7. (Optional): In the Description field, enter the description you are to describe the order.

  8. In the Return Order Line Items area, click Add Return Order Line Item on the right. The Search Orders and Order Line Items window is displayed. All the orders containing sales order line items that you can return for the account are listed for your selection.

    SearchOrdersandOrderLineItemsWindow.jpg

  9. Click the corresponding order in the Order column to display the order line item to return in the Order Line Items column, and then select the order line item to return by selecting the corresponding checkbox. If several orders are listed, you can search for the order containing the sales order line item you are to return by entering the order number in the Search By Order Number field.

  10. After you are finished, click Next. The sales order line item to return is added to the Return Order Line Items area.

    ReturnOrderLineItemsArea.png

  11. Edit detailed information about the return order line item. You can edit the following fields:

    Field name Description
    Item Name Required field. Name of the return order line item. This name represents the name of the object that is returned and is typically displayed on invoices, credit memos, and so on.
    Bill Target Date

    Required field. The date when the return order line item is invoiced. Credit memos are generated for return order line items if you have enabled the Invoice Settlement feature; otherwise, negative invoices are generated.

    Billing Trigger Rule The default value is Without Fulfillment, select it  As FulfillmentOccurs for a return order line item with fulfillments. If As Fulfillment Occurs is selected, you are allowed to add fulfillments and the billing documents will be generated at the fulfillment level based on the Bill Target Date and Item State specified for the fulfillments.
    Item State

    State of the return order line item. Valid values are Executing, Booked, Sent To Billing, Complete, and Canceled. By default, the starting state of an order line item is Executing.

    • If you want to create fulfillments on the return order line item, set this field to Booked.
    • If you want to generate billing documents for the return order line item, set the field to Sent To Billing.
    For more information, see State transitions for an order, order line item, and fulfillment.
    Quantity to Return / Availability
    • Quantity to Return: The quantity you are to return for the original sales order line item. The quantity to return must be less than or equal to the quantity available to return.
    • Availability: This is a field for reference. Check this field for the quantity available to return.
    Actions

    You can perform the following actions through this field:

    • Click the edit icon  icon-edit.png  to display the Edit Order Line Items window and edit more fields of the return order line item.
    • Click the delete icon icon-delete.png to delete the current return order line item. 
  12. (Optional): You can add more return order line items as you need in the current order. See Steps 8 - 11 in Create an order and add a return order line item. The maximum number of order line items allowable in an order is 100.

  13. Click Activate to activate the order.

Create a return order line item from an existing order details page

Complete the following steps:

  1. Log in to the Zuora application and then navigate to Customers > Orders. The Orders page opens.
  2. Enter the order number of the order that contains the sales order line item you are to return in the Search By Order Number field. The corresponding order is listed for your selection.
  3. Click the order number in the Order column. The order details page opens.
  4. Click Create Return Order at the top right. The Create New Order page opens and all the sales order line items that you can return from the existing order are listed in the Return Order Line Items area.

    ReturnOrderLineItemsArea2.png

  5. Edit detailed information about the return order line items. You can edit the following fields:

    Field name Description
    Item Name Required field. Name of the return order line item. This name represents the name of the object that is returned and is typically displayed on invoices, credit memos, and so on.
    Bill Target Date

    Required field. The date when the return order line item is invoiced. Credit memos are generated for return order line items if you have enabled the Invoice Settlement feature; otherwise, negative invoices are generated.

    Billing Trigger Rule The default value is Without Fulfillment, select it  As FulfillmentOccurs for a return order line item with fulfillments. If As Fulfillment Occurs is selected, you are allowed to add fulfillments and the billing documents will be generated at the fulfillment level based on the Bill Target Date and Item State specified for the fulfillments rather than the Bill Target Date and Item State specified for your order line item.
    Item State

    State of the return order line item. Valid values are Executing, Booked, Sent To Billing, Complete, and Canceled. By default, the starting state of an order line item is Executing.

    If you want to create fulfillments on the return order line item, set this field to Booked. If you want to generate billing documents for the return order line item, set the field to Sent To Billing.

    For more information, see State transitions for an order, order line item, and fulfillment.

    Quantity to Return / Availability
    • Quantity to Return: The quantity you are to return for the original sales order line item. The quantity to return must be less than or equal to the quantity available to return.
    • Availability: This is a field for reference. Check this field for the quantity available to return.
    Actions

    You can perform the following actions through this field:

    Click the edit icon  icon-edit.png  to display the Edit Order Line Items window and edit more fields of the return order line item. Click the delete icon icon-delete.png to delete the current return order line item. 
  6. (Optional): You can add more return order line items as you need in the current order. See Steps 8 - 11 in Create an order and add a return order line item. The maximum number of order line items allowable in an order is 100.

  7. Click Activate to activate the order.

Create fulfillments on a return order line item

After activating the return order line item, you can create fulfillments on the return order line item.

Complete the following steps:

  1. On the return orders details page, click the item name in blue in the ITEM NAME column in the Return Order Line Items area. The order line item details page opens.
  2. Click Create Fulfillment at the top right. The fulfillment details page opens.
  3. On the fulfillment details page, edit the following fields in the Overview and Fulfillment Integration areas:

    Field name

    Description

    Fulfillment Quantity

    Required field. The quantity of the fulfillment items to be returned. The value must be less than or equal to the value shown in the Quantity Remaining for Delivery field.

    Fulfillment Date

    Required field. The date of the fulfillment.

    Carrier

    The express company.

    Tracking Number

    The express number from the express company.

    State

    The state of the fulfillment. Valid values are Executing, Booked, Sent To Billing, Complete, and Canceled. The default value is Executing.

    • If the fulfillment is in the Executing state, you can edit the fields in this table.
    • If the fulfillment is specified to other states, you can add fulfillment items to the fulfillment. To generate billing documents, you need to specify the fulfillment to the Sent To Billing state and set the Billing Target Date field.

    Billing Target Date

    Specify the date when the fulfillment will be invoiced.

    After setting this field to the Sent To Billing state and specifying a value for this field, you can create a bill run. For instructions, see Create Bill Runs

    Description

    The description of the fulfillment for reference purposes.

    Fulfillment System

    The value that maps an external value from the ERP system, for example, the value can be NetSuite, SAP, or other specific fulfillment partners.

    Fulfillment Location

    The occurring location of the fulfillment.

    External ID

    Specify the ID of the fulfillment. The ID is generated based on the external system.

  4. (Optional) Change the State to a state except Executing to add fulfillment items, click Add Item to add a fulfillment item, and then edit the following fields in the Fulfillment Items area.

    Field name

    Description

    Item Identifier

    Specify the ID of the fulfillment item. The ID is provided by customers.

    Description

    The description of the fulfillment item for reference purposes.

    After editing, click the save icon icon-save.png to finish adding the fulfillment item. You can create multiple fulfillment items, but the number of fulfillment items should not be greater than the value of the Fulfillment Quantity field.

  5. Click Save at the top right on the fulfillment details page to finish the fulfillment creation. If you return to the order line item details page, you can view the created fulfillments in the Fulfillment Details section. For more information, see View the details of a fulfillment.
  6. (Optional) To generate billing documents for the fulfillment in the Sent To Billing state, create a bill run. For instructions, see Create Bill Runs.

Use the REST API

Use the Create an order operation to create a return 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 a return order line item:

    • existingAccountNumber: This must be set to the order account that owns the sales order line item to return.

    • category: This must be set as Return for an order to contain the return order line item.

    • itemName: The name of the return order line item

    • itemCategory: This must be set as Return for a return order item.

    • itemState: State of the return order line item. Valid values are Executing, Booked, Sent To Billing, Complete, and Canceled. By default, the starting state of an order line item is Executing. If you want to create fulfillment on the return order line item, set this field to Booked.

  • originalOrderNumber: the order number of the order containing the sales order line item to return

  • originalOrderLineItemNumber: the order line item number of the sales order line item to return

  • quantity: The quantity you are to return for the original sales order line item. The quantity to return must be less than or equal to the quantity of the original sales order line item.

  • billingRule: Specify this field to TriggerAsFulfillmentOccurs to allow you to create fulfillments on the return order line item and generate billing documents for the fulfillments.

The following API request creates a return order line item from an existing sales order line item and allows you to create fulfillments on the return order line item.

 

Request POST /v1/orders
Request Body
{
"existingAccountNumber": "AN_1660044119927",
"orderDate": "2022-01-01",
"category": "Return",
"orderLineItems": [
{
"itemName": "Return Item",
"itemCategory": "Return",
"originalOrderNumber": "O-000001",
"originalOrderLineItemNumber": "1",
"quantity": 2,
"transactionStartDate": "2022-01-01",
"transactionEndDate": "2022-01-01",
"itemState": "Booked",
"billingRule": "TriggerAsFulfillmentOccurs"
}
]
}

Use the Create fulfillments operation to create a return fulfillment. Keep the following points in mind when you run the "Create fulfillments" operation:

  • Determine the following fields and other required custom fields for a return order line item:

    • fulfillmentType: The value should be  Return.

    • fulfillment date: The date of the fulfillment.

    • Quantity: The quantity of the fulfillment items to be returned. The value must be less than or equal to the value in the quantityPendingFulfillment field.

    • State: State of the fulfillment. Valid values are Executing, Booked, Sent To Billing, Complete, and Canceled.

    • orderLineItemId: Specify the ID of the return order line item on which you want to create the fulfillments.

  • If you want to generate the invoice for the fulfillment of the return order line item, you need to further consider the following:

    • Use the State and billTargetDate fields to determine that the fulfillments can be invoiced on the specified billing target date. Credit memos are generated for fulfillments if you have enabled the Invoice Settlement feature; otherwise, negative invoices are generated. For the fulfillment to be invoiced, its state must be SentToBilling. When a bill run is created, it picks up fulfillments to be invoiced based on the billTargetDate field.

    • Use the processingOptions field to determine whether a billing document should be generated and whether payment should be collected along with the order creation.

The following API request creates a fulfillment on the return order line item:

Request POST {{host}}/apps/v1/fulfillments
Request Body
{
"fulfillments": [
{
"fulfillmentDate": "2022-01-02",
"quantity": 2,
"description": "return fulfillment",
"state": "SentToBilling",
"billTargetDate": "2022-01-02",
"orderLineItemId": "4028828c82819b74018286e02e041bdc",
"fulfillmentType": "Return",
"trackingNumber": "T-0009874"
}
]
}