logo

Returns

The returns API allows you to do following:

  1. Create return orders
  2. Get return order details
  3. Cancel return order

ReturnsCreateOrder

Creates return order for inspection.

SecurityBEARER
Request
Request Body schema: application/json
required
rma
required
string

RMA of the return, typically generated by the merchant.

externalReturnId
required
string

A unique reference to the return order in the external system submitting the request.

object (DeliverrAddress)

Source address indicating where the return is being shipped from. Required if no externalLabel is provided.

name
required
string
company
string
street1
required
string
street2
string
city
required
string
zip
required
string
state
required
string
country
required
string
phone
string
email
string
isResidential
boolean
required
Array of objects (RequestedReturnItem) non-empty

Items contained in the return.

Array (non-empty)
identifier
required
string

The unique identifier for the item that must already be known to the system. Ideally this is the LOGISTICS_SKU but we also support the merchant SKU if it has been associated with the product via the Products API. Returns containing items that are not known to the system will be rejected.

type
required
string (ReturnItemType)

The type of identifier provided. Must be one of LOGISTICS_SKU, SKU.

Enum: "LOGISTICS_SKU" "SKU"
quantity
required
number <double> >= 1

The number of items with the given identifier in the return.

object (ExternalLabel)

Required if the return label was purchased externally. If omitted a label will be purchased.

trackingCode
required
string

The tracking code of the label.

carrier
required
string

The name of the carrier providing the label.

trackingUrl
string

The tracking URL, if available.

labelUrl
string

The URL of the label, if available.

logisticsOrderId
string

Logistics ID of the original order, if available

Responses
201

Return order details

400

Bad Request

401

Unauthorized

422

Unprocessable Entity

post/logistics/api/2023-10/returns
Request samples
application/json
{
  • "rma": "string",
  • "externalReturnId": "string",
  • "sourceAddress": {
    • "name": "string",
    • "company": "string",
    • "street1": "string",
    • "street2": "string",
    • "city": "string",
    • "zip": "string",
    • "state": "string",
    • "country": "string",
    • "phone": "string",
    • "email": "string",
    • "isResidential": true
    },
  • "returnItems": [
    • {
      • "identifier": "string",
      • "type": "LOGISTICS_SKU",
      • "quantity": 1
      }
    ],
  • "externalLabel": {
    • "trackingCode": "string",
    • "carrier": "string",
    • "trackingUrl": "string",
    • "labelUrl": "string"
    },
  • "logisticsOrderId": "string"
}
Response samples
application/json
{
  • "id": 0,
  • "status": "CREATED",
  • "sourceAddress": {
    • "name": "string",
    • "company": "string",
    • "street1": "string",
    • "street2": "string",
    • "city": "string",
    • "zip": "string",
    • "state": "string",
    • "country": "string",
    • "phone": "string",
    • "email": "string",
    • "isResidential": true
    },
  • "shippingLabel": {
    • "carrier": "string",
    • "trackingCode": "string",
    • "trackingUrl": "string",
    • "labelUrl": "string",
    • "trackingStatus": "CREATED"
    },
  • "rma": "string",
  • "externalReturnId": "string",
  • "returnItems": [
    • {
      • "identifier": "string",
      • "expectedQuantity": 0,
      • "inspectedItems": [
        ]
      }
    ],
  • "shippedAt": "2019-08-24T14:15:22Z",
  • "receivedAt": "2019-08-24T14:15:22Z",
  • "inspectedAt": "2019-08-24T14:15:22Z"
}

GetReturns

SecurityBEARER
Request
query Parameters
externalReturnId
string
rma
string
trackingCode
string
status
Array of strings (ReturnOrderStatus)
Items Enum: "CREATED" "SHIPPED" "RECEIVED_FOR_PROCESSING" "PROCESSED" "CANCELLED"
limit
integer <int32> [ 1 .. 250 ] characters
page_info
string
Responses
200

Paginated Return Orders

Response Schema: application/json
Array
id
required
number <double>

Unique identifier of the return.

status
required
string (ReturnOrderStatus)

The current status of the return.

Enum: "CREATED" "SHIPPED" "RECEIVED_FOR_PROCESSING" "PROCESSED" "CANCELLED"
object (DeliverrAddress)

Source address where the return was shipped from, if known.

required
object (ShippingLabel)

The label used to ship the return.

rma
required
string

RMA of the return.

externalReturnId
required
string

A unique reference to the return order in the external system submitting the request.

required
Array of objects (ReturnItem)

Items contained in the return.

shippedAt
string <date-time>

Date when the return was shipped.

receivedAt
string <date-time>

Date when the return was received at the warehouse.

inspectedAt
string <date-time>

Date when the return was inspected at the warehouse.

400

Bad Request

401

Unauthorized

422

Unprocessable Entity

get/logistics/api/2023-10/returns
Response samples
application/json
[
  • {
    • "id": 0,
    • "status": "CREATED",
    • "sourceAddress": {
      • "name": "string",
      • "company": "string",
      • "street1": "string",
      • "street2": "string",
      • "city": "string",
      • "zip": "string",
      • "state": "string",
      • "country": "string",
      • "phone": "string",
      • "email": "string",
      • "isResidential": true
      },
    • "shippingLabel": {
      • "carrier": "string",
      • "trackingCode": "string",
      • "trackingUrl": "string",
      • "labelUrl": "string",
      • "trackingStatus": "CREATED"
      },
    • "rma": "string",
    • "externalReturnId": "string",
    • "returnItems": [
      • {
        }
      ],
    • "shippedAt": "2019-08-24T14:15:22Z",
    • "receivedAt": "2019-08-24T14:15:22Z",
    • "inspectedAt": "2019-08-24T14:15:22Z"
    }
]

ReturnsGetOrder

Get return by returnId. This will include ReturnOrder, ReturnItems with inspection status and ShippingLabel.

SecurityBEARER
Request
path Parameters
returnId
required
number <double>

Unique ID used to track the return.

Responses
200

Return details

Response Schema: application/json
id
required
number <double>

Unique identifier of the return.

status
required
string (ReturnOrderStatus)

The current status of the return.

Enum: "CREATED" "SHIPPED" "RECEIVED_FOR_PROCESSING" "PROCESSED" "CANCELLED"
object (DeliverrAddress)

Source address where the return was shipped from, if known.

name
required
string
company
string
street1
required
string
street2
string
city
required
string
zip
required
string
state
required
string
country
required
string
phone
string
email
string
isResidential
boolean
required
object (ShippingLabel)

The label used to ship the return.

carrier
required
string

The name of the carrier providing the label.

trackingCode
required
string

The tracking code of the label.

trackingUrl
string

The tracking URL, if available.

labelUrl
string

The URL of the label, if available.

trackingStatus
required
string (ReturnOrderTrackingStatus)

The current tracking status of the return.

Enum: "CREATED" "SHIPPED" "DELIVERED" "CANCELLED" "FAILED"
rma
required
string

RMA of the return.

externalReturnId
required
string

A unique reference to the return order in the external system submitting the request.

required
Array of objects (ReturnItem)

Items contained in the return.

Array
identifier
required
string

The identifier provided when creating the return item.

expectedQuantity
required
number <double>

The quantity provided when creating the return item.

required
Array of objects (InspectedItem)

The list of items with the given identifier that have completed inspection at the warehouse.

shippedAt
string <date-time>

Date when the return was shipped.

receivedAt
string <date-time>

Date when the return was received at the warehouse.

inspectedAt
string <date-time>

Date when the return was inspected at the warehouse.

400

Bad Request

401

Unauthorized

404

Not Found

get/logistics/api/2023-10/returns/{returnId}
Response samples
application/json
{
  • "id": 0,
  • "status": "CREATED",
  • "sourceAddress": {
    • "name": "string",
    • "company": "string",
    • "street1": "string",
    • "street2": "string",
    • "city": "string",
    • "zip": "string",
    • "state": "string",
    • "country": "string",
    • "phone": "string",
    • "email": "string",
    • "isResidential": true
    },
  • "shippingLabel": {
    • "carrier": "string",
    • "trackingCode": "string",
    • "trackingUrl": "string",
    • "labelUrl": "string",
    • "trackingStatus": "CREATED"
    },
  • "rma": "string",
  • "externalReturnId": "string",
  • "returnItems": [
    • {
      • "identifier": "string",
      • "expectedQuantity": 0,
      • "inspectedItems": [
        ]
      }
    ],
  • "shippedAt": "2019-08-24T14:15:22Z",
  • "receivedAt": "2019-08-24T14:15:22Z",
  • "inspectedAt": "2019-08-24T14:15:22Z"
}

ReturnsCancelOrder

Cancel a return that was created. Return will not be cancelled if it is received.

SecurityBEARER
Request
path Parameters
returnId
required
string

Unique ID used to track the return.

Responses
204

Successfully cancelled the return

400

Bad Request

401

Unauthorized

404

Not Found

post/logistics/api/2023-10/returns/{returnId}/cancel
Response samples
application/json
{
  • "status": 400,
  • "type": "string",
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}
➔ Next to Events