A Buy with Prime return is an action that a customer takes to return previously-delivered items that they purchased in a Buy with Prime order.

Currently, you can create Buy with Prime returns for eligible items only within the Buy with Prime merchant console, and customers can create returns within the online returns center.

If you subscribe to Buy with Prime return events, you're notified of returns by event types that start with RETURN, such as the RETURN_STARTED event, RETURN_COMPLETED event, and so on. For details about what to do when you receive one of these events, see Steps to Process Returns.

When you process returns, you call the order query for more information about the return. The response provides information such as return status updates, return item details, return creation time, and so on. This information helps you understand the overall return process and status. The following image shows the fields of the order query response that are pertinent to returns. (Click the image to enlarge it.)

You can associate each external return with one or more identifiers called aliases, which are in the returns.details.aliases field of the order. If you use aliases for a return, it is crucial to ensure that the aliases that you provide for the return are unique and aren't already associated with other returns in the order.

Each alias has an aliasId and an aliasType. We strongly recommend that you provide a unique aliasId that you can use when you call the updateOrder mutation to add or update return details.

You can add and update external return aliases related to the order by calling the updateOrder mutation. To update external return aliases in a Buy with Prime order, you pass a new, complete list of aliases. The new list of aliases will replace the existing list of aliases. For example, to delete all aliases, pass an empty list of aliases.

For requests and responses of different ways to update external return aliases, see the following examples:

• Replace external return aliases in a Buy with Prime order
• Add an external return alias to a Buy with Prime order
• Delete an external return alias in a Buy with Prime order

A return reason code specifies the reason for the return. Amazon has the following set of default return reason codes.

A Buy with Prime refund is a process by which a customer is reimbursed for an item that they ordered, which is then returned or cancelled. A return always leads to a refund.

For details, see Synchronize Refunds.

Throughout the shopper journey, customers interact with returns in the following ways.

• Pre-checkout: As a customer browses products on your site, the site (product detail page, search page, and so on) shows whether a Buy with Prime item is eligible for return. You provide this information by getting a reversal offer.
• Checkout: On your site's checkout pages, the customer sees whether each of the Buy with Prime items in the order is eligible for a return. As with pre-checkout, you provide this information by getting a reversal offer.
• Post-order: After the customer places the order and the Buy with Prime items are delivered to the customer, the customer can check the shopper order detail page to see whether each of the Buy with Prime items in the order is eligible for return along with a deadline for the return.
• Return creation: You or the customer creates a return for return-eligible Buy with Prime items in an order within the return window. Currently, you can create Buy with Prime returns only within the Buy with Prime merchant console, and customers can create returns within the online returns center. Returns can only be created for Buy with Prime items that have been delivered to the customer.
• Return: The customer drops off the item according to their chosen return transportation method, and the item is then shipped and returned to an Amazon fulfillment center. To handle returns, see Steps to Process Returns.
• Refund: Every Buy with Prime return is associated with a refund. You issue a refund to the customer when you are notified by the REFUND_REQUESTED event. To handle refunds, see Steps to Process Refunds.

A Buy with Prime order with only one item can have only one associated return. However, a Buy with Prime order with multiple items or multiple quantities of the same item can be associated with multiple returns as follows:

• You or the customer can create different returns for each item separately.
• You or the customer can create different returns with partial quantities of the same item.
• You or the customer can create different returns for different items at different points in time.

For example, consider an order in which two units of item A and one unit of item B were delivered. The customer might create the following two returns:

• Return 1 with the first unit of item A
• Return 2 with the second unit of item A and one unit of item B

The following example shows a response to a query to get the details of the order.

{
  "data": {
    "order": {
      "id": "example-order-id",
      "returns": {
        "details": [
          {
            "id": "example-return-id-1",
            "createdAt": "2022-02-03T18:17:19Z",
            "updatedAt": "2022-02-03T18:17:19Z",
            "state": "CREATED",
            "returnFor": {
              "returnOrderLineItems": [
                {
                  "lineItem": {
                    "id": "example-line-item-id-1"
                  },
                  "returnedQuantity": {
                    "amount": 1
                  }
                }
              ]
            }
          },
          {
            "id": "example-return-id-2",
            "createdAt": "2022-02-04T18:17:19Z",
            "updatedAt": "2022-02-04T18:17:19Z",
            "state": "CREATED",
            "returnFor": {
              "returnOrderLineItems": [
                {
                  "lineItem": {
                    "id": "example-line-item-id-1"
                  },
                  "returnedQuantity": {
                    "amount": 1
                  }
                },
                {
                  "lineItem": {
                    "id": "example-line-item-id-2"
                  },
                  "returnedQuantity": {
                    "amount": 1
                  }
                }
              ]
            }
           }  
         ]
       }
     }
   }
 }

Reversal is a term that the Buy with Prime API uses to encompass the concepts of returns, refunds, and cancellations.

At a high level, a Buy with Prime reversal offer specifies whether the item (or multiple items that are bought together) can be returned by evaluating a set of conditions specified in the returns policy found at About Our Returns Policies, which you must follow and incorporate into your existing policies. A reversal offer contains the following information (some of which is nested inside the reversal offer object):

• id: The unique identifier of the reversal offers response.
• expiresAt: The timestamp by which the reversal offers expire.
• reversalOfferCollection: A list of items and associated reversal offers. Each item in the list contains the item ID and its associated reversal offers. Each reversal offer has an item and a summary.
• summary: A title, description, list of resolution types, and a window, as follows:
  • title and description: Strings that you can display to shoppers on the product detail page, the checkout page, and so on. The strings contain return eligibility (returnable/non-returnable) and the return window (for example, 30 days from order delivery).
  • resolutionTypes: The available return resolutions to the shopper. If the RETURN resolution isn’t present, the item isn't eligible for return.
  • window: Eligible time window in which the shopper can return the product. The window is available as an absolute date (such as 2024-01-30T23:59:59Z for a holiday window) or a number of days (for example, 30 days). You can use the resolution types and window to display custom messages or UI elements.