Create Return

In the event that a customer wishes to return an item, the Create Return API can start the process by initializing the return instance.

Supported FormatsJSON

The .json address above can be used to access the schema within Postman. An example use of the Create Return API follows below, or view the schema or the sample Postman Collection.

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.


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.

itemarrayThe items included in the return.
creationSourceenumThe source where the return was created ("CCUI", "API", or "FULFILLER"). OMS will automatically set this parameter if this API request is being triggered from the CCUI or Fulfiller interfaces. If this parameter is not provided, then it will default to "API".

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.

returnItemIDintegerA unique identifier for the return item.
orderItemIDintegerA unique identifier for the order item. The minimum value is "0".
quantityintegerThe number of items being returned. The minimum value is "1".
returnSubtotalnumberThe amount the customer will be reimbursed for the item.
fulfillerSubtotalnumberThe subtotal the fulfiller will receive from the return for this item.
statusenumThe return item’s current status (ACCEPTED, PENDING, or REJECTED).
reasonstringThe reason the item is being returned.
partNumberstringThe part number for the product, an identifier unique to the manufacturer. The minimum length is 1 and the maximum length is 50.
UPCstringThe Universal Product Code for this product. The maximum length is 50.
SKUstringThe Stock Keeping Unit code for this product. the maximum length is 50.
partNamestringThe name of the product.
orderItemUnitsarrayList of order item units associated to return with their unique identifiers and attributes. The minimum length is 0.
optionsarrayList of order item product options.
giftCardInfoobjectThe information needed when the return item is a gift card.

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.

orderItemUnitIDintegerA unique identifier for order item units.
serialNumbernumberThe serial number for an individual unit within an item.

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

toNamestringThe name of the gift card recipient. The maximum length is 85.
fromNamestringThe name of the gift card purchaser. The maximum length is 85.
emailstringThe email address of the consumer. The maximum length is 250.
messagestringA message to be included with the card. The maximum length is 400.
deliveryDatestringThe date for the card to be delivered. Supports date-time format.
printFormbooleanWhether a form for the gift card should be printed or not. The default is "false".
giftCardTypeenumA gift card payment type (GC, GT, GX, IM, M1, M2, M3, or VA).
cardIssuerenumThe abbreviation for the card issuer (SV, CL, or VL), used for GC payment types only.
giftCardValuenumberThis is the optional value of the gift card. If not set, then the value will be actualPrice.

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:

returnIDintegerA unique identifier for the return. The minimum value is "1".
returnLocationintegerA unique identifier for the fulfillment location. The minimum value is "1".
externalOrderIDstringA client-generated unique identifier for the order. The minimum length is 1 and the maximum value is 100.
statusenumThe return’s current status (OPEN, PROCESSING, or CLOSED).
returnTotalnumberThe total amount of the return.
returnReductionTotalnumberThe amount to subtract from returnTotal to get the amount refunded to customer.
fulfillerTotalnumberThe amount the fulfiller will receive from the return.
createdTimestringThe time the return was created. Supports date-time format.
clearedTimestringThe time the return was cleared. Supports date-time format.
confirmTimestringThe time the return was accepted/rejected. Supports date-time format.
refundTypeenumThe type of refund that will be processed (STANDARD or GIFT_CARD).
orderIDintegerA unique identifier for the order. The minimum value is "1".
shipmentIDintegerA unique identifier for the shipment. The minimum value is "1".

The Full Request

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

Any optional 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 OMS.

    "reason":"Item did not fit."

ProductOMS Dev: Create Return