# Steps to Process Refunds > 📘 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. [block:html]{"html":"\n Sign Up\n"}[/block] A Buy with Prime *refund* is a process by which a shopper is reimbursed for an item that they ordered, which is then returned or canceled. There are several possible reasons for refunds. For example, a shopper might cancel or return an item, the merchant might cancel the order, or the order is canceled because it is unfulfillable. The way you handle a refund depends on whether the refund was requested through Buy with Prime or through your system (an *external* refund): * **Refunds requested through Buy with Prime:** You are notified of these refunds through the [`REFUND_REQUESTED`](https://documents.buywithprime.amazon.com/bwp-api/docs/refund_requested) event. In this case, you [handle refund events](#steps-to-handle-refund-events) and [update refunds](#steps-to-update-refunds) in the Buy with Prime order with the latest details. * **External refunds**: The associated Buy with Prime order initially has no record of these refunds. In this case, you [add a refund](#steps-to-add-an-external-refund) to the Buy with Prime order after you issue the refund to the shopper. If there are further updates to the refund on your end, you can [update refunds](#steps-to-update-refunds) in the Buy with Prime order with the latest details. # Steps to add an external refund If a refund is requested externally to Buy with Prime, take the following steps to add the refund to the Buy with Prime order. Before you do these steps, you must initiate an external refund for the order and refund the shopper. You must also have a unique identifier associated with the external refund. There can be scenarios in which the external refund details that you provide in the [`updateOrder`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-mutations-updateorder) mutation conflict with ongoing refunds that are requested through Buy with Prime and vice versa. For details on how to handle these conflicts, see [External refund synchronization issues](https://documents.buywithprime.amazon.com/bwp-api/docs/troubleshoot-refund-errors#external-refund-synchronization-issues). 1. [Add the refund to the Buy with Prime order.](#step-1-add-the-refund-to-the-buy-with-prime-order) 2. [Update the Buy with Prime order with refund details.](#step-2-update-the-buy-with-prime-order-with-refund-details) ## Step 1: Add the refund to the Buy with Prime order After you have the unique identifier associated with the external refund, use the [`updateOrder`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-mutations-updateorder) mutation to add a refund to the Buy with Prime order. The following example shows a request and response. In the request: * There is no Buy with Prime refund ID, because Buy with Prime doesn't have a record of the refund yet. * We highly recommend that you provide a unique `alias` for the refund. Each `alias` has an `aliasType` and an `aliasId`. Ensure that the `aliasId` that you provide is unique and not already associated with other refunds present in the order. * The `refundTotal` is mandatory and contains the total amount that you refunded to the shopper. * You should provide a `state` for the refund. However, if you don't provide a state for the refund, the state defaults to `PENDING`. * If you don't provide line items or the amount for the line items, the refund amount will be applied to the whole order. A successful response indicates that refund was successfully added to the Buy with Prime order. You will only receive a [`REFUND_REQUESTED`](https://documents.buywithprime.amazon.com/bwp-api/docs/refund_requested) event if you add an externally issued refund in the `PENDING` state.
Request ```text GraphQL // GraphQL mutation mutation updateOrder { updateOrder( orderIdentifier: { orderId: "example-order-id" } input: { returns: { details: [ { aliases: [ { aliasType: "EXTERNAL-REFUND-ID", aliasId: "example-external-refund-id" } ], state: PENDING, refundTotal: { totalAmount: { amount: 2, currencyCode: "USD" } }, returnFor: { orderLineItemAmounts: [ { lineItem: { id: "external-line-item-id" }, amount: { value: 2 } } ] } } ] } } ) } ```
Response ```json { "data": { "updateOrder": { "order": { "id": "example-order-id", "returns": { "details": [ { "id": "return-id-123", "createdAt": "xyz789", "updatedAt": "xyz790", "state": "PENDING", "aliases": [ { "aliasType": "EXTERNAL-REFUND-ID", "aliasId": "example-external-refund-id" } ], "refundTotal": { "totalAmount": { "amount": 2, "currencyCode": "USD" } }, "returnLineItems": [ { "id": "return-line-item-123", "returnFor": { "orderLineItemAmounts": [ { "amount": { "value": 2 }, "lineItem": { "id": "external-line-item-id", "amount": { "value": 2 } } } ] } } ] } ] } } } } } ```
## Step 2: Update the Buy with Prime order with refund details As you process a refund in your order management system, you must update the Buy with Prime order with the latest refund details. To update the refund details in the Buy with Prime order, call the [`updateOrder`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-mutations-updateorder) mutation. For details, see [Steps to update refunds](#steps-to-update-refunds). To identify the external refund to the [`updateOrder`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-mutations-updateorder) mutation, use the `aliasId` that you specified when you [added the refund](#step-1-add-the-refund-to-the-buy-with-prime-order) to the order. # Steps to handle refund events This section describes how to process refunds that are requested through Buy with Prime. The starting point for processing a refund is when you receive a [`REFUND_REQUESTED`](https://documents.buywithprime.amazon.com/bwp-api/docs/refund_requested) event. 1. [Subscribe to the `REFUND_REQUESTED` event.](#step-1-subscribe-to-the-refund_requested-event) 2. [Parse the `REFUND_REQUESTED` event.](#step-2-parse-the-refund_requested-event) 3. [Get the refund details from the response.](#step-3-get-the-refund-details-from-the-event) 4. [Recalculate the refund amount.](#step-4-recalculate-the-refund-amount) 5. [Initiate the refund with your order management system.](#step-5-initiate-the-refund-with-your-order-management-system) 6. [Update the Buy with Prime order with refund details.](#step-6-update-the-buy-with-prime-order-with-refund-details) ## Step 1: Subscribe to the `REFUND_REQUESTED` event Before you can process refunds, you must subscribe to the [`REFUND_REQUESTED`](https://documents.buywithprime.amazon.com/bwp-api/docs/refund_requested) Buy with Prime event. You subscribe and receive notifications for Buy with Prime events using webhook events or through [Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html). For details on subscribing to webhook events, see [Steps to Subscribe to Buy with Prime Events using Webhook Events](https://documents.buywithprime.amazon.com/bwp-api/docs/steps-to-subscribe-to-buy-with-prime-events-using-webhook-events). For details on subscribing to events with Amazon EventBridge, see [Steps to Subscribe to Buy with Prime Events using Amazon EventBridge](https://documents.buywithprime.amazon.com/bwp-api/docs/steps-to-subscribe-to-buy-with-prime-events-using-amazon-eventbridge). ## Step 2: Parse the `REFUND_REQUESTED` event When you receive a [`REFUND_REQUESTED`](https://documents.buywithprime.amazon.com/bwp-api/docs/refund_requested) event, parse the `resources` array of the event to get the refund ID. For details about how to interpret the `resources` array of an event, see [Subscribe to Events](https://documents.buywithprime.amazon.com/bwp-api/docs/subscribe-to-events). For example, in the following event, the refund ID is `example-refund-id`. ```json { "idempotencyKey":"example-idempotency-key", "eventDescriptor": "REFUND_REQUESTED", "resources": [ "businessProduct/business-product-id/order/order-id/refund/example-refund-id" ], "eventId":"example-event-id", "apiVersion": "2024-11-01", "subscriptionId": "example-subscription-id", "eventTime":"2025-01-20T12:34:56Z", "data": "example-return-event-data-payload", } ``` ## Step 3: Get the refund details from the event When you receive the event, examine the `refunds.details` array in the [`order`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-objects-order) object. This array contains a list of refunds, each with an associated refund ID. For details about the fields, see [`RefundDetails`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-objects-refunddetails). The following example event's [`order`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-objects-order) object shows that the refund ID specified by the event (`example-refund-id`) includes one item. The refunded item has a line item ID of `example-line-item-id`, the requested refund amount is $10, and the refund is pending.
Response ```json { "idempotencyKey":"example-idempotency-key", "eventDescriptor": "REFUND_REQUESTED", "resources": [ "businessProduct/business-product-id/order/order-id/refund/example-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" } } ] } } ] } } }, } ```
## Step 4: Recalculate the refund amount In the previous step, you retrieved the refund details from the event's `data` object. In the response, the `refundTotal` field contained the estimated refund amount. However, the estimated refund amount in the `refundTotal` field might not be entirely accurate, complete, or up-to-date. The `refundTotal` is just an estimate based on Buy with Prime policies and the data that you initially provided. We therefore strongly recommend that you recalculate the amount that you want to refund to the shopper before you issue the refund in the next step. ## Step 5: Initiate the refund with your order management system After you recalculate the refund amount in the previous step, issue a refund to the shopper in your order management system. You must adhere to [Amazon's refund policies](https://www.amazon.com/gp/help/customer/display.html/?nodeId=GKQNFKFK5CF3C54B). In the next step, you update the Buy with Prime order with the refund details. ## Step 6: Update the Buy with Prime order with refund details As you process a refund in your order management system, you must update the Buy with Prime order with the latest refund details. To update the refund details in the Buy with Prime order, call the [`updateOrder`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-mutations-updateorder) mutation. For details, see [Steps to update refunds](#steps-to-update-refunds). # Steps to update refunds As you process a refund in your order management system, you must update the Buy with Prime order with the latest refund details. These updates enable, for example, the refund details to display correctly to the shopper when they check their order using the online returns center. To update the refund details in the Buy with Prime order, call the [`updateOrder`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-mutations-updateorder) mutation. You typically call [`updateOrder`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-mutations-updateorder) multiple times to keep the Buy with Prime order up to date on the details of the refund until the refund is complete. For example requests and responses, see [Update Refund Details](https://documents.buywithprime.amazon.com/bwp-api/docs/update-refund-details). > 🚧 Important > > You can associate refunds with one or more identifiers called *aliases*. For important information about how to call [`updateOrder`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-mutations-updateorder) to update or add aliases, see [Refund alias](https://documents.buywithprime.amazon.com/bwp-api/docs/synchronize-refunds#refund-alias). In the following example, assume that a $10 refund was requested and that you issue the refund in two partial payments of $4 and $6. 1. [Start the refund.](#step-1-start-the-refund) 2. [Complete the refund.](#step-2-complete-the-refund) ## Step 1: Start the refund When you start the refund, call [`updateOrder`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-mutations-updateorder) to set the following [`RefundDetails`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-objects-refunddetails): * Set the refund `state` to `PENDING` ,`PARTIAL`, `SUCCESS`, or `FAILURE`, depending on your use case. The available states depend on the current refund state. For a list of allowable refund states that you can set, see [Refund state](https://documents.buywithprime.amazon.com/bwp-api/docs/synchronize-refunds#refund-state). In this example, we set the state to `PARTIAL` because this update is for a partial refund. If you don't provide the state, the Buy with Prime API leaves the state as it is. If you call the [`order`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-queries-order) query, you can see the state information in `data.order.refunds.details.paymentDetails.state` in the response. * Set the amounts for the `refundTotal` and `paymentDetails` to $4. * In the `aliases` array, specify alias types such as external identifiers that you want to associate with this refund. In the following example, there is an external refund ID with `your-oms-refund-id` as an external identifier.
Request ```text GraphQL // GraphQL mutation mutation updateOrder { updateOrder( orderIdentifier: { orderId: "example-order-id" } input: { refunds: { details: [ { id: "example-refund-id" aliases: [ { aliasType: "EXTERNAL_REFUND_ID" aliasId: "your-oms-refund-id" } ] refundTotal: { totalAmount: { amount: 4, currencyCode: "USD" } } state: PARTIAL refundFor: { orderLineItems: [ { lineItemId: { lineItemId: "example-line-item-id" } } ] } paymentDetails: [ { id: "example-payment-transfer-id-1" amount: { amount: 4, currencyCode: "USD" } paymentMethod: { displayString: "Visa ending in [REDACTED:CREDIT_DEBIT_NUMBER]" type: AMAZON_PAY } state: SUCCESS } ] } ] } } ) } ```
## Step 2: Complete the refund Call [`updateOrder`](https://documents.buywithprime.amazon.com/bwp-api/docs/order-mutations-updateorder) when you refund the remaining $6 and mark the refund as a `SUCCESS`, as shown in the following example request. Following these examples, the refund total is $10 because you refunded $4 in the previous step.
Request ```text   // GraphQL mutation mutation updateOrder { updateOrder( orderIdentifier: { orderId: "example-order-id" } input: { refunds: { details: [ { id: "example-refund-id" aliases: [ { aliasType: "EXTERNAL_REFUND_ID" aliasId: "your-oms-refund-id" } ] refundTotal: { totalAmount: { amount: 10, currencyCode: "USD" } } state: SUCCESS refundFor: { orderLineItems: [ { lineItemId: { lineItemId: "example-line-item-id" } } ] } paymentDetails: [ { id: "payment-transfer-id-2" amount: { amount: 6, currencyCode: "USD" } paymentMethod: { displayString: "Visa ending in [REDACTED:CREDIT_DEBIT_NUMBER]" type: AMAZON_PAY } state: SUCCESS } ] } ] } } ) } ```
# Related topics * [Add an External Refund](https://documents.buywithprime.amazon.com/bwp-api/docs/add-an-external-refund) * [Get Refund Details](https://documents.buywithprime.amazon.com/bwp-api/docs/get-refund-details) * [Update Refund Details](https://documents.buywithprime.amazon.com/bwp-api/docs/update-refund-details) * [Synchronize Refunds](https://documents.buywithprime.amazon.com/bwp-api/docs/synchronize-refunds) * [Create and Manage Orders](https://documents.buywithprime.amazon.com/bwp-api/docs/create-and-manage-orders)