Create Return

If a customer wants to return an item, the Create Return API can start the process by initializing the return instance.

Note that the request body and parameter schemas outlined in this guide are the exact same as in the previous version of OMS, as the Unified Commerce platform supports backwards compatibility for this API. The only change to this request is the format of the base endpoint, as shown in the below table. Remember to provide the x-vol-tenant key for authentication in the headers.

Note that the Order ID and Shipment ID must be appended to the endpoint, so that OMS will find the appropriate order/shipment to be associated with the return.

Example

The example case creates an API call for a return that has the following properties:

• Return made from Order 098765 and Shipment 012345
• Quantity – One
• Disposition Reason – Item did not fit

This guide will demonstrate how to put together each section of the request to build this return. It is a very basic use case, and much more complex returns can be built with additional information as described below.

Required Parameters

There are two required parameters – the Return Item object and the origination point of the return object, though this is a special case that will default appropriately if not specified in the API request by the user.

These items (/item/[object]) are built with the following parameters. Only orderItemID and quantity are required for each item in the array, while the other datapoints may be provided if desired.

The options array (/item/options/[string]) is just a list of strings describing the order options.

The units (/item/orderItemUnits/[object]) that make up the orderItemUnits array have two possible parameters. Only orderItemUnitID is required.

The gift card information (/item/giftCardInfo/[object]) has a number of parameters, but only giftCardType is required.

Optional Parameters

A number of other variables for the main Return API can be provided, based on what information the return case should have associated with it. This includes parameters such as:

The Full Request

This is the endpoint that would be called to create a return from Order 098765 and Shipment 012345.

https://{tenantId}-translation.mozu.com/api/v2/return/?orderID=098765&shipmentID=012345

Any of the above available parameters could be appended to the body of the request as needed. Note how the required Return Item is built as an object with its own set of parameters. Additionally, the creationSource value is not being set in this example even though it is a required element of the Return object because it will appropriately default to “API” once submitted to the system.

{
 "item":[
  {
    "orderItemID":0000000,
    "quantity":"1",
    "reason":"Item did not fit."
  }
 ]
}