In the event that a customer wishes to return an item, the Create Return API can start the process by initializing the return instance.
The .json address above can be used to access the schema within Postman. An example use of the Create Return API follows here — or go directly to 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.
There is only one required parameter: the Return Item object.
|item||array||The 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.
|returnItemID||integer||A unique identifier for the return item.|
|orderItemID||integer||A unique identifier for the order item. The minimum value is "0".|
|quantity||integer||The number of items being returned. The minimum value is "1".|
|returnSubtotal||number||The amount the customer will be reimbursed for the item.|
|fulfillerSubtotal||number||The subtotal the fulfiller will receive from the return for this item.|
|status||enum||The return item’s current status (ACCEPTED, PENDING, or REJECTED).|
|reason||string||The reason the item is being returned.|
|partNumber||string||The part number for the product, an identifier unique to the manufacturer. The minimum length is 1 and the maximum length is 50.|
|UPC||string||The Universal Product Code for this product. The maximum length is 50.|
|SKU||string||The Stock Keeping Unit code for this product. the maximum length is 50.|
|partName||string||The name of the product.|
|orderItemUnits||array||List of order item units associated to return with their unique identifiers and attributes. The minimum length is 0.|
|options||array||List of order item product options.|
|giftCardInfo||object||The 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.
|orderItemUnitID||integer||A unique identifier for order item units.|
|serialNumber||number||The 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.
|toName||string||The name of the gift card recipient. The maximum length is 85.|
|fromName||string||The name of the gift card purchaser. The maximum length is 85.|
|email||string||The email address of the consumer. The maximum length is 250.|
|message||string||A message to be included with the card. The maximum length is 400.|
|deliveryDate||string||The date for the card to be delivered. Supports date-time format.|
|printForm||boolean||Whether a form for the gift card should be printed or not. The default is "false".|
|giftCardType||enum||A gift card payment type (GC, GT, GX, IM, M1, M2, M3, or VA).|
|cardIssuer||enum||The abbreviation for the card issuer (SV, CL, or VL), used for GC payment types only.|
|giftCardValue||number||This is the optional value of the gift card. If not set, then the value will be actualPrice.|
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:
|returnID||integer||A unique identifier for the return. The minimum value is "1".|
|returnLocation||integer||A unique identifier for the fulfillment location. The minimum value is "1".|
|externalOrderID||string||A client-generated unique identifier for the order. The minimum length is 1 and the maximum value is 100.|
|status||enum||The return’s current status (OPEN, PROCESSING, or CLOSED).|
|returnTotal||number||The total amount of the return.|
|returnReductionTotal||number||The amount to subtract from returnTotal to get the amount refunded to customer.|
|fulfillerTotal||number||The amount the fulfiller will receive from the return.|
|createdTime||string||The time the return was created. Supports date-time format.|
|clearedTime||string||The time the return was cleared. Supports date-time format.|
|confirmTime||string||The time the return was accepted/rejected. Supports date-time format.|
|refundType||enum||The type of refund that will be processed (STANDARD or GIFT_CARD).|
|orderID||integer||A unique identifier for the order. The minimum value is "1".|
|shipmentID||integer||A 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."