📘

Buy with Prime API is now available for early access

Sign up for early access to the Buy with Prime API using the 'Sign Up' button below. The API may change as Amazon receives feedback and iterates on it.

Sign Up

The REFUND_REQUESTED event is published when there is a request to issue a refund for one or more items. Typically, this event is generated after returned items purchased using Buy with Prime are scanned at a carrier facility. A REFUND_REQUESTED event is also published after the PACKAGE_DELIVERY_CANCELLED event.

You must process this event. The expected result of processing this event is that the merchant's order management system issues a refund to the customer.

The following examples are ways that you might use this event:

• To enable customers to return an item through Amazon's self-service order return center and receive their refund. This helps customers feel confident in purchasing with the merchant and choosing Buy with Prime.
• To enable merchants to issue a refund to a customer as soon as the customer returns an item.

Required permission

To subscribe to this event, your API credentials must have at least Read Order permission. You choose permissions when you generate your API credentials. For details, see Authenticate to the Buy with Prime API.

Schema

{
    "idempotencyKey":"example-idempotency-key",
    "eventDescriptor": "REFUND_REQUESTED",
    "resources": [
        "businessProduct/business-product-id/order/order-id/refund/refund-id"
    ],
    "eventId":"example-event-id",
    "apiVersion": "2024-11-01",
    "subscriptionId": "example-subscription-id",
    "eventTime":"2025-01-20T12:34:56Z",
    "data": {}
}

{
    "version": "0",
    "id": "example-event-id",
    "detail-type": "REFUND_REQUESTED",
    "source": "aws.partner/buywithprime/partner-event-source-name",
    "account": "example-aws-account-id",
    "time": "2025-01-20T12:34:56Z",
    "region": "us-east-1",
    "resources": [
        "businessProduct/business-product-id/order/order-id/refund/refund-id"
    ], 
    "detail": {
        "idempotencyKey":"example-idempotency-key",
        "eventDescriptor": "REFUND_REQUESTED",
        "resources": [
            "businessProduct/business-product-id/order/order-id/refund/refund-id"
        ],
        "eventId":"example-event-id",
        "apiVersion": "2024-11-01",
        "subscriptionId": "example-subscription-id",
        "eventTime":"2025-01-20T12:34:56Z",
        "data": {}
    }
}

{
    "version": "0",
    "id": "example-event-id",
    "detail-type": "REFUND_REQUESTED",
    "source": "aws.partner/buywithprime/partner-event-source-name",
    "account": "example-aws-account-id",
    "time": "2025-01-20T12:34:56Z",
    "region": "us-east-1",
    "resources": [
        "businessProduct/business-product-id/order/order-id/refund/refund-id"
    ], 
    "detail": {}
}

Fields

Detail fields

Handling the event

When you receive this event, you typically query the order to fetch more information about which products the shopper wants refunded. Take the following steps:

1. Parse the resources array of the event to get the order ID and the refund ID.

2. Using the order ID that you found in the resources array in the previous step, make an API call to the order query. For examples of how to perform this query, see Query a Buy with Prime Order.

3. In the response, navigate to the refunds.details array and find the element with the refund ID that you found in the resources array of the event in step 1. There, you will find the IDs of the line items being refunded.

   Note: Depending on the moment that you call the Buy with Prime API with respect to refund processing, the value of the state attribute of the refund is either PENDING or SUCCESS. A refund in SUCCESS state has already been processed and no further action is needed.

4. If you need additional product information about the line items being refunded, see the corresponding element in order.lineItems array in the response.

5. Issue a refund to the customer by using your order management system. After you issue the refund, call the updateOrder mutation to update the refund status.

Related topics

• Subscribe to Events
• Event Types
• Steps to Subscribe to Buy with Prime Events