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.
From an implementation perspective, you handle refunds in the same manner regardless of how the refund was initiated. The Buy with Prime refund event notifies you when to issue a refund; you receive and handle the event.
This topic describes how to handle Buy with Prime refunds.
Prerequisites
Before 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.
The following procedure begins when you receive a REFUND_REQUESTED event.
Steps to process refunds
This section describes how to process Buy with Prime refunds. The starting point for processing a refund is when you receive a REFUND_REQUESTED event.
- 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: 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 2: 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
}
refundedQuantity {
amount
}
}
}
paymentDetails {
id
amount {
currencyCode
amount
}
paymentMethod {
displayString
type
}
state
}
}
}
}
}
Step 3: 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"
},
"refundedQuantity": {
"amount": 1
}
}
]
},
"paymentDetails": []
}
]
}
}
}
}
Step 4: 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. 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 5: 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 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. Syncing refund details with the Buy with Prime order enables, 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, you call the updateOrder mutation. You typically call the updateOrder mutation 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.
For example, if a $10 refund is requested and you issue the refund in two partial payments of $4 and $6, you call updateOrder when you start the refund and when you complete the refund, as described next.
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
}
}
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 3 days ago