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.


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

  • 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 is only one required parameter: the Return Item object.

itemarrayThe items included in the return.

These items (/item/[object]) are built with the following parameters. Only orderItemID and quantity are required for each item in the array.

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 entire request that will create a basic return. Any optional parameters could be appended as needed. Note how the required Return Item is built as an object with its own set of parameters.

    "reason":"Item did not fit."

ProductOMS Dev: Create Return