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 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.
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.
|item||array||The items included in the return.|
|creationSource||enum||The 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.
|returnItemID||integer||A unique identifier for the return item. This is a read-only value that will be generated by OMS after the return is created, so do not attempt to provide it in the request body. It will be displayed in the return item data of the response.|
|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. This is a read-only value that is calculated by OMS after the return is created, so do not attempt to provide it in the request body. It will be displayed in the return item data of the response.|
|fulfillerSubtotal||number||The subtotal the fulfiller will receive from the return for this item. This is a read-only value that is calculated by OMS after the return is created, so do not attempt to provide it in the request body. It will be displayed in the return item data of the response.|
|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 used for GC (Gift Card) payment types only. See the Create Order guide for the full list of payment types.|
|giftCardValue||number||This is the optional value of the gift card. If not set, then the value will be actualPrice.|
|orderGiftCertInfoId||integer||The gift card ID that is automatically set by OMS. This is a ready-only value, so not attempt to include this parameter in the request – it will be displayed in the gift card information of the response.|
|giftCardPayType||string||The pay type of the gift card. This is also a read-only value that is automatically set by OMS, so do not include it in the request. It will be displayed in the gift card information of the response.|
|orderID||integer||The ID of the order that this gift card is related to. This is a read-only value that is automatically set by OMS based on the other return information, so do not attempt to include it in the request. It will be displayed in the gift card information of the response.|
|itemID||integer||The ID of the gift card item. This is also a read-only value that is automatically set by OMS, so do not include it in the request. It will be displayed in the gift card information of the response.|
|rmaID||integer||The ID of the RMA that this gift card is associated with. This is also a read-only value that is automatically set by OMS, so do not include it in the request. It will be displayed in the gift card information of the response.|
|giftCardNumber||string||The gift certificate number of the gift card. This is also a read-only value that is automatically set by OMS, so do not include it in the request. It will be displayed in the gift card information of the response.|
|isDigital||boolean||Whether the gift card is digital or a physical card.|
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 endpoint that would be called to create a return from Order 098765 and Shipment 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 OMS.
"reason":"Item did not fit."