---
title: "listReturns"
method: GET
path: "/externalFulfillment/2024-09-11/returns"
tags: ["External Fulfillment Returns v2024-09-11"]
---

# listReturns

`GET /externalFulfillment/2024-09-11/returns`

Retrieve a list of return items. You can filter results by location, RMA ID, status, or time.

## Query parameters

- `returnLocationId` string
- `rmaId` string
- `status` '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'
- `reverseTrackingId` string
- `createdSince` string, date-time
- `createdUntil` string, date-time
- `lastUpdatedSince` string, date-time
- `lastUpdatedUntil` string, date-time
- `lastUpdatedAfter` string, date-time
- `lastUpdatedBefore` string, date-time
- `maxResults` integer
- `nextToken` string

## Response `200`

Success. The response contains a list of return items.

- ReturnsResponse — The response to the `listReturns` operation.
  - `returns` Return[] — A list of returns.
    - `id` string, required — The return item's ID.
    - `returnLocationId` string — The SmartConnect identifier for where the return item was dropped for delivery.
    - `merchantSku` string — The seller's identifier for the SKU.
    - `returnType` 'CUSTOMER' | 'REJECT', required — The type of return.
    - `returnSubType` 'NORMAL' | 'REPLACEMENT' | 'EXCHANGE' — The sub-type of return.
    - `numberOfUnits` integer — The total number of units in the return.
    - `status` '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', required — The current status of the return.
    - `fulfillmentLocationId` string, required — The ID of the location that fulfilled the order.
    - `creationDateTime` string, date-time — Defines a date and time according to ISO8601.
    - `lastUpdatedDateTime` string, date-time, required — Defines a date and time according to ISO8601.
    - `returnMetadata` ReturnMetadata, required — Metadata about the return item.
      - `returnReason` string, required — The reason for the return.
      - `rmaId` string — The RMA ID of the return.
      - `fulfillmentOrderId` string — The SmartConnect ID of the fulfillment order for which the return was placed.
      - `invoiceInformation` InvoiceInformation — Invoice-related information for the return created for Amazon SmartConnect.
        - `id` string, required — The unique ID of the invoice that corresponds to the return.
    - `returnShippingInfo` ReturnShippingInfo, required — Information about the shipping of the return packages.
      - `deliveryDateTime` string, date-time — Defines a date and time according to ISO8601.
      - `pickupDateTime` string, date-time — Defines a date and time according to ISO8601.
      - `forwardTrackingInfo` TrackingInfo — Information for tracking a return.
        - `carrierName` string, required — The name of the third party courier service used to ship the return package.
        - `trackingId` string, required — The tracking ID of the return package.
      - `reverseTrackingInfo` TrackingInfo — Information for tracking a return.
        - `carrierName` string, required — The name of the third party courier service used to ship the return package.
        - `trackingId` string, required — The tracking ID of the return package.
    - `marketplaceChannelDetails` MarketplaceChannelDetails, required — Marketplace channel-specific attributes for the return. These attributes are not mandatory and each channel can provide them differently.
      - `marketplaceChannel` MarketplaceChannel — The marketplace and channel name.
        - `marketplaceName` string — The name of the marketplace.
        - `channelName` string — The name of the channel within the marketplace.
      - `merchantId` string — The ID of the merchant or seller to whom this return is created in the marketplace.
      - `shipmentId` string — The marketplace-specific shipment ID.
      - `customerOrderId` string — The marketplace-specific customer order ID.
      - `returnLocationId` string — The Amazon SmartConnect ID of the location to which this return is created.
      - `channelSku` string — The Amazon SmartConnect SKU of the channel.
      - `exchangeOrderId` string — The Amazon SmartConnect ID of the exchange order.
    - `otpDetails` OtpDetails — One-time password (OTP) details of the return item.
      - `otp` string, required — One-time password to validate the return delivered to the seller.
      - `validTill` integer, required — The UNIX timestamp of when the verification code expires.
    - `packageDeliveryMode` 'WITH_OTP' | 'WITHOUT_OTP' — The package delivery mode. This indicates whether the return was delivered to the seller with or without a one-time password (OTP).
    - `replanningDetails` ReplanningDetails — Provides details about the replanned returns.
      - `previousTrackingInfo` TrackingInfo[] — A list of all the previous tracking information for the return.
        - `carrierName` string, required — The name of the third party courier service used to ship the return package.
        - `trackingId` string, required — The tracking ID of the return package.
  - `nextToken` string — A token that you use to retrieve the next page of results. The response includes `nextToken` when there are multiple pages of results. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until `nextToken` is null. Note that this operation can return empty pages.

## Other responses

- `400` — Request has missing or invalid parameters and cannot be parsed.
- `403` — Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.
- `404` — The resource specified does not exist.
- `409` — The resource specified conflicts with the current state
- `413` — The request size exceeded the maximum accepted size.
- `415` — The request payload is in an unsupported format.
- `429` — The frequency of requests was greater than allowed.
- `500` — An unexpected condition occurred that prevented the server from fulfilling the request.
- `503` — Temporary overloading or maintenance of the server.

---

[API](https://skmtc.net/aws-samples/apis/a-content-management-v2020-11-01.md) · [All operations](https://skmtc.net/aws-samples/apis/a-content-management-v2020-11-01/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws-samples/a-content-management-v2020-11-01/revisions/815a5b6dbaa6/schema)