REFUND_REQUESTED

📘

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.

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 shopper.

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

  • To enable shoppers to return an item through Amazon's self-service order return center and receive their refund. This helps shoppers feel confident in purchasing with the merchant and choosing Buy with Prime.
  • To enable merchants to issue a refund to a shopper as soon as the shopper 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

Schema for webhook destinations
{
    "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": {
        "order": {
            "id": "example-order-id",
            "aliases": [
                {
                    "aliasId": "example-alias-id",
                    "aliasType": "example-alias-type"
                }
            ],
            "refunds": {
                "details": [
                    {
                        "id": "example-refund-id",
                        "createdAt": "example-created-at-datetime-string",
                        "updatedAt": "example-updated-at-datetime-string",
                        "state": "example-refund-state-string",
                        "refundRequestReason": "example-refund-request-reason-string",
                        "refundStatusReason": "example-refund-status-reason-string",
                        "refundTotal": {
                        "totalAmount": {
                            "amount": 20.0,
                            "currencyCode": "example-currency-code-string"
                            }
                        },
                        "refundFor": {
                            "orderLineItems": [
                                {
                                    "lineItem": {
                                        "id": "a7a2458ebd-7975599522"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        }
    },
}
Schema for Amazon EventBridge destinations
{
    "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": {
            "order": {
                "id": "example-order-id",
                "aliases": [
                    {
                        "aliasId": "example-alias-id",
                        "aliasType": "example-alias-type"
                    }
                ],
                "refunds": {
                    "details": [
                        {
                            "id": "example-refund-id",
                            "createdAt": "example-created-at-datetime-string",
                            "updatedAt": "example-updated-at-datetime-string",
                            "state": "example-refund-state-string",
                            "refundRequestReason": "example-refund-request-reason-string",
                            "refundStatusReason": "example-refund-status-reason-string",
                            "refundTotal": {
                            "totalAmount": {
                                "amount": 20.0,
                                "currencyCode": "example-currency-code-string"
                                }
                            },
                            "refundFor": {
                                "orderLineItems": [
                                    {
                                        "lineItem": {
                                            "id": "a7a2458ebd-7975599522"
                                        }
                                    }
                                ]
                            }
                        }
                    ]
                }
            }
        },
    }
}
Schema for Amazon EventBridge destinations (Deprecated)
{
    "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

KeyData typeDescription
versionStringAmazon EventBridge event version.
idStringAmazon EventBridge-generated UUID for an event.
detail-typeStringType schema for the detail of the event, which in this case is REFUND_REQUESTED.
sourceStringName of the partner event source in Amazon EventBridge. For details, see Subscribe to Events.
accountStringAWS account ID that hosts the partner event source.
timeStringISO 8601 timestamp that indicates when the event was published.
regionStringAWS region from which the event is published.
resourcesArray of stringsArray of identifiers for the resources that triggered the event, in key-value pair format. Each resource identifier is a string that starts with businessProduct/{businessProductId}/, followed by resource types (keys) and resource IDs (values) separated by slashes. For details about how to interpret resources, see Subscribe to Events.
detailObjectJSON object that contains details about the event. You can call the Buy with Prime API to find further information about the resource(s) specified in the resources array. For details, see detail fields.

Detail fields

KeyData typeDescription
idempotencyKeyStringUnique identifier to detect duplicate events.
eventDescriptorStringEvent type that determines the default query.
resourcesArray of stringsArray of identifiers for the resources that triggered the event, in key-value pair format. Each resource identifier is a string that starts with businessProduct/{businessProductId}/, followed by resource types (keys) and resource IDs (values) separated by slashes. This field is the same value as resources at the top level.
eventIdStringUnique identifier for this event. This field is the same value as id at the top level.
apiVersionStringBuy with Prime API version associated with this event.
subscriptionIdStringUnique identifier for an event subscription.
eventTimeStringISO 8601 timestamp that indicates when the event was published. This field is the same value as time at the top level.
dataObjectJSON object that can contain API response data. The REFUND_REQUESTED event's data payload contains the refund's associated order object.

Handling the event

When you receive this event, you typically parse the included order information found in the data object 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 refund ID.
  2. In the data object, navigate to the refunds.details array and find the element with the refund ID that you found in the resources array of the event. The element with the refund ID contains the IDs of the line items being refunded.
  3. If you need additional product information about the line items being refunded, see the corresponding element in order.lineItems array in the data object.
  4. Issue a refund to the shopper using your order management system. After you issue the refund, call the updateOrder mutation to update the refund status.

If you require information not found in the data object, query the order using the order ID found in the resources array.

Related topics