API docs by Redocly

Selling Partner API for Amazon External Fulfillment Return Item Processing (2021-08-19)

Download OpenAPI specification:Download

Selling Partner API Test Support: smartconnect-support@amazon.com URL: https://github.com/amzn/amazon-marketplace-api-sdk/issues License: Amazon Software License

This section provides APIs for selling partners to work with Amazon External Fulfillment returns management services.

returnRetrieval

listReturns

Get a list of return items dropped for the seller in the specified node, and in the specified status. Returns can be further filtered based on their creation date/time

query Parameters
returnLocationId
string

The SmartConnect location identifier for which return items are to be retrieved

rmaId
string

The RMA id of the return items to be listed

status
string
Enum: "CREATED" "CARRIER_NOTIFIED_TO_PICK_UP_FROM_CUSTOMER" "CARRIER_OUT_FOR_PICK_UP_FROM_CUSTOMER" "CUSTOMER_CANCELLED_PICK_UP" "CUSTOMER_RESCHEDULED_PICK_UP" "PICKED_FROM_CUSTOMER" "IN_TRANSIT" "OUT_FOR_DELIVERY" "DELIVERED" "REPLANNED" "CUSTOMER_DROPPED_OFF" "PARTIALLY_PROCESSED" "PROCESSED" "REJECTED" "CANCELLED"

Retrieves only those return items which are in the specified status. The most common use-case would be to fetch all new return items which would be in the CREATED status. Valid values are CREATED, CARRIER_NOTIFIED_TO_PICK_UP_FROM_CUSTOMER, CARRIER_OUT_FOR_PICK_UP_FROM_CUSTOMER, CUSTOMER_CANCELLED_PICK_UP, CUSTOMER_RESCHEDULED_PICK_UP, PICKED_FROM_CUSTOMER, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED

reverseTrackingId
string

The reverseTrackingId of the return items to be listed

createdSince
string <date-time>

Return items whose creation is after the specified date/time are included in the response. This field should be in the ISO8601 date/time format.

createdUntil
string <date-time>

Return items whose creation is before the specified date/time are included in the response. This field should be in the ISO8601 date/time format.

lastUpdatedSince
string <date-time>

Return items whose last update is after the specified date/time are included in the response. This field should be in the ISO8601 date/time format. Only to be used along with returnLocationId and status params.

lastUpdatedUntil
string <date-time>

Return items whose last update is before the specified date/time are included in the response. This field should be in the ISO8601 date/time format. Only to be used along with returnLocationId and status params.

lastUpdatedAfter
string <date-time>

DEPRECATED. Use createdFrom param instead for same results. Return items whose creation is after the specified date/time are included in the response. This field should be in the ISO8601 date/time format.

lastUpdatedBefore
string <date-time>

DEPRECATED. Use createdTo param instead for same results. Return items whose creation is before the specified date/time are included in the response. This field should be in the ISO8601 date/time format.

maxResults
integer <int64> <= 100

Specify the number of return items to be included in the response. It will default to 10 in case not provided. Maximum limit is 100.

nextToken
string

A cursor representing information about the next page of returns. Use the value returned in previous calls to page through the complete list of returns.

Responses

Response samples

Content type
application/json
{
  • "nextToken": "eyJsYXN0VXBkYXRlZFRpbWVzdGFtcCI6eyJzIjpu",
  • "returns": [
    ]
}

getReturn

Get a single return item with the specified id.

path Parameters
returnId
required
string

The id of the return item to be retrieved.

Responses

Response samples

Content type
application/json
{
  • "marketplaceChannelDetails": {
    },
  • "otpDetails": {
    },
  • "packageDeliveryMode": "WITH_OTP",
  • "creationDateTime": "2021-05-08T01:23:33Z",
  • "fulfillmentLocationId": "450a6661-1a97-4abd-99e4-45714bcf4439",
  • "id": "ee39cdd9-9caa-47b6-a5b1-7b6a1c6d43d1",
  • "lastUpdatedDateTime": "2021-05-08T10:23:38Z",
  • "merchantSku": "SerialYT1",
  • "numberOfUnits": 1,
  • "returnMetadata": {
    },
  • "returnShippingInfo": {
    },
  • "returnType": "CUSTOMER",
  • "status": "CARRIER_NOTIFIED_TO_PICK_UP_FROM_CUSTOMER"
}

returnProcessing

processReturnItem

Process a return by grading. Determine the item condition and update the quantities for each item condition.

path Parameters
returnId
required
string

The id of the return item to be retrieved.

header Parameters
x-amzn-idempotency-token
required
string

A unique token/requestId provided with each call to ensure idempotency.

Request Body schema: application/json-patch+json

The body of the request.

op
required
string
Value: "increment"

The operation to be performed. Only 'increment' is supported in this API

path
required
string

A JSON pointer. Use '/processedReturns'

required
object (ItemConditions)

Incremental quantities for each item condition in key/value pair format. Available item conditions are Sellable, Defective, CustomerDamaged, CarrierDamaged, Fraud, WrongItem. At least one item condition is required

Responses

Request samples

Content type
application/json-patch+json
{
  • "op": "increment",
  • "path": "string",
  • "value": {
    }
}

Response samples

Content type
application/json
{ }