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.
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. There are several possible reasons for refunds. For example, a customer might cancel or return an item, the merchant might cancel the order, or the order is cancelled 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_REQUESTEDevent. In this case, you handle refund events and 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 to the Buy with Prime order after you issue the refund to the customer. If there are further updates to the refund on your end, you can update refunds in the Buy with Prime order with the latest details.
This topic describes how to add, handle, and update refunds.
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 customer. 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 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.
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 mutation to add a refund to the Buy with Prime order.
The following example shows a request and response. Note that 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
aliasfor the refund. Eachaliashas analiasTypeand analiasId. Ensure that thealiasIdthat you provide is unique and not already associated with other refunds present in the order. - The
refundTotalis mandatory and contains the total amount that you refunded to the customer. - You should provide a
statefor the refund. However, if you don't provide a state for the refund, the state defaults toPENDING. - 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 event if you add an externally issued refund in the PENDING state.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "example-order-id"
refunds: {
details: [
{
aliases: [
{
aliasType: "EXTERNAL-REFUND-ID",
aliasId: "example-external-refund-id"
}
]
refundTotal: { totalAmount: { amount: 2, currencyCode: "USD" } }
state: PENDING
refundFor: {
orderLineItems: [
{
lineItemId: {
lineItemId: "external-line-item-id"
}
refundedQuantity: { amount: 1.0 }
}
]
}
}
]
}
}
) {
order {
id
refunds {
details {
id
aliases {
aliasType
aliasId
}
state
refundTotal {
totalAmount {
amount
}
}
refundFor {
orderLineItems {
lineItem {
id
}
amount {
value
}
}
}
updatedAt
}
}
}
}
}
Response
{
"data": {
"updateOrder": {
"order": {
"id": "example-order-id",
"refunds": {
"details": [
{
"id": "example-refund-id-from-buy-with-prime",
"updatedAt": "2024-06-25T07:37:24.907Z",
"state": "PENDING",
"aliases": [
{
"aliasType": "EXTERNAL-REFUND-ID",
"aliasId": "example-external-refund-id"
}
],
"refundTotal": {
"totalAmount": {
"amount": 2.0
}
},
"refundFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"value": 1
}
}
]
}
}
]
}
}
}
}
}
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 mutation. For details, see Steps to update refunds.
To identify the external refund to the updateOrder mutation, use the aliasId that you specified when you added the refund 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 event.
- Subscribe to the
REFUND_REQUESTEDevent. - Parse the
REFUND_REQUESTEDevent. - Query the order.
- Get the refund details from the response.
- Recalculate the refund amount.
- Initiate the refund with your order management system.
- Update the Buy with Prime order with refund details.
Step 1: Subscribe to the REFUND_REQUESTED event
REFUND_REQUESTED eventBefore you can process refunds, you must subscribe to the REFUND_REQUESTED Buy with Prime event.
You subscribe and receive notifications for Buy with Prime events through Amazon EventBridge. For details, see Steps to Subscribe to Buy with Prime Events.
Step 2: Parse the REFUND_REQUESTED event
REFUND_REQUESTED eventWhen you receive a REFUND_REQUESTED event, parse the resources array of the event to get the order ID and refund ID. For details about how to interpret the resources array of an event, see How to handle events.
For example, in the following event, the order ID is example-order-id and the refund ID is example-refund-id.
{
"version": "0",
"id": "example-event-id",
"detail-type": "REFUND_REQUESTED",
"source": "aws.partner/buywithprime/{partnerEventSourceName}",
"account": "123456789012",
"time": "2024-02-14T12:34:56Z",
"region": "us-east-1",
"resources": [
"businessProduct/example-business-product-id/order/example-order-id/refund/example-refund-id",
],
"detail": {}
}
Step 3: Query the order
Call the order query to get all the refunds requested for that order, as shown in the following example request.
Request
// GraphQL query
query order {
order(orderId: "example-order-id") {
id
refunds {
details {
id
state
aliases {
aliasType
aliasId
}
createdAt
updatedAt
refundTotal {
totalAmount {
currencyCode
amount
}
}
refundFor {
orderLineItems {
lineItem {
id
}
amount
}
}
paymentDetails {
id
amount {
currencyCode
amount
}
paymentMethod {
displayString
type
}
state
}
}
}
}
}
Step 4: Get the refund details from the response
In the response to the order query that you performed in the previous step, examine the refunds.details array. This array contains a list of refunds, each with an associated refund ID. For details about the fields, see RefundDetails. For an example request and response, see Get Refund Details.
The following example response 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
{
"data": {
"order": {
"id": "example-order-id",
"refunds": {
"details": [
{
"id": "example-refund-id",
"state": "PENDING",
"aliases": [],
"createdAt": "2024-04-03T14:14:18.160Z",
"updatedAt": "2024-04-03T14:14:18.410Z",
"refundTotal": {
"totalAmount": {
"currencyCode": "USD",
"amount": 10.00
}
},
"refundFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": 1
}
]
},
"paymentDetails": []
}
]
}
}
}
}
Step 5: Recalculate the refund amount
In the previous step, you retrieved the refund details by using the Buy with Prime API. 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 customer before you issue the refund in the next step.
Step 6: Initiate the refund with your order management system
After you recalculate the refund amount in the previous step, issue a refund to the customer in your order management system. You must adhere to Amazon's refund policies when issuing refunds for Buy with Prime products.
In the next step, you update the Buy with Prime order with the refund details.
Step 7: 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 mutation. For details, see 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 customer when they check their order using the online returns center.
To update the refund details in the Buy with Prime order, call the updateOrder mutation. You typically call 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.
Important
You can associate refunds with one or more identifiers called aliases. For important information about how to call
updateOrderto update or add aliases, see 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.
Step 1: Start the refund
When you start the refund, call updateOrder to set the following RefundDetails:
-
Set the refund
statetoPENDING,PARTIAL,SUCCESS, orFAILURE, 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.In this example, we set the state to
PARTIALbecause 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
orderquery, you can see the state information indata.order.refunds.details.paymentDetails.statein the response. -
Set the amounts for the
refundTotalandpaymentDetailsto $4. -
In the
aliasesarray, 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 withyour-oms-refund-idas an external identifier.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "example-order-id"
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 1234"
type: AMAZON_PAY
}
state: SUCCESS
... Payment details ...
}
]
}
]
}
}
) {
id
}
}
Step 2: Complete the refund
Call updateOrder when you refund the remaining $6 and mark the refund as a SUCCESS, as shown in the following example request. Note that although the payment amount is $6, the refund total is $10 ($6 plus the $4 you previously refunded).
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "example-order-id"
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 1234"
type: AMAZON_PAY
}
state: SUCCESS
...Payment details...
}
]
}
]
}
}
) {
id
}
}
Related topics
Updated 2 days ago