Steps to Process Returns
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 return is an action that a customer takes to return previously-delivered items that they purchased in a Buy with Prime order.
You process Buy with Prime returns by using the Return interface and the Order interface of the Buy with Prime API.
This topic describes how to process Buy with Prime returns.
Prerequisites
Before you can process returns, you must subscribe to the following Buy with Prime events:
RETURN_STARTEDRETURN_DELIVERY_IN_TRANSITRETURN_DELIVERY_COMPLETEDRETURN_DELIVERY_FAILEDRETURN_ITEM_GRADEDRETURN_COMPLETED
In this topic, we hereafter refer to these events as return events.
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 one of these events.
Steps to process returns
This section describes how to process Buy with Prime returns. The starting point for processing a return is when you receive a return event. Return events are listed in Prerequisites.
All you do for return events is to update the information in your order management system. You don't provide a refund until you receive a REFUND_REQUESTED event, as described in Steps to process Buy with Prime refunds.
The following procedure tells you what to do after receive a return event.
- Parse the return event.
- Query the order.
- Identify the returned items within the order.
- Check the return status of the items.
- Update your order management system.
Step 1: Parse the return event
When you receive a return event, parse the resources array of the event to get the order ID and return 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 return ID is example-return-id.
{
"version": "0",
"id": "example-event-id",
"detail-type": "RETURN_STARTED",
"source": "aws.partner/buywithprime/partner-event-source-name",
"account": "example-aws-account-id",
"time": "2023-10-27T12:34:56Z",
"region": "us-east-1",
"resources": [
"businessProduct/business-product-id/order/example-order-id/return/example-return-id",
],
"detail": {}
}
Step 2: Query the order
Call the order query of the Buy with Prime API to get the return details for that order. For an example request and response, see Get return details for an order.
Step 3: Identify the returned items within the order
In the response to the order query that you performed in the previous step, navigate to the returnFor object. This object enables you to identify the line items involved in the return process.
The following example response to the order query shows that the return (example-return-id ) specified by the event includes one item. The response also includes the return delivery details with example-return-package-id, and return line-item details with grading information for example-return-line-item-id.
{
"data": {
"order": {
"id": "example-order-id",
"lineItems": [
{
"id": "example-line-item-id",
"createdAt": "2024-05-28T20:18:55.196Z",
}
],
"returns": {
"details": [
{
"id": "example-return-id",
"createdAt": "2024-05-28T20:22:22.512677135Z",
"updatedAt": "2024-05-28T20:22:22.512677135Z",
"state": "COMPLETED",
"returnDeliveryDetails": [
{
"id": "example-return-package-id",
"state": "COMPLETED",
"trackingDetails": {
"trackingId": "example-tracking-id",
"carrierCode": "UPS"
},
"returnDeliveryFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id",
"amount": {
"unit": "ONE",
"value": 1
}
}
}
]
}
}
],
"returnLineItems": [
{
"id": "example-return-line-item-id",
"grading": {
"summary": {
"gradedAmount": {
"unit": "ONE",
"value": 1
},
"unitWiseCondition": [
{
"amount": {
"unit": "ONE",
"value": 1
},
"condition": "Sellable"
}
]
}
},
"orderLineItem": {
"amount": {
"unit": "ONE",
"value": 1
},
"lineItem": {
"id": "example-line-item-id",
}
}
}
],
"returnFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
}
}
]
}
}
}
}
Step 4: Check the return status of the items
In the response to the order query, examine the state field within the return details to determine the current status of the overall return request. The state has one of the following values:
- A state of
CREATEDindicates an ongoing return process (a return was placed by a customer but not yet dropped off, a return package is in transit, or a package reached a fulfillment center and grading is in progress). - A state of
COMPLETEDsignifies a successfully closed return (grading is complete for all items of that return request across return packages).
The RETURN_DELIVERY_IN_TRANSIT and RETURN_DELIVERY_COMPLETED events are related to the return package. To determine the current status of the return package, examine the state field in the returnDeliveryDetails . The state has one of the following values:
- A state of
CREATEDindicates that the customer created a return but hasn't dropped off the package yet. - A state of
IN_TRANSITindicates that the package was dropped off by the customer and is in transit to the fulfillment center. - A state of
COMPLETEDsignifies that the package was successfully delivered to the fulfillment center for further processing such as grading. - A state of
FAILEDindicates that a return package failed to be delivered to the fulfillment center.
The returnDeliveryDetails also contains details such as the tracking ID and carrier code.
The RETURN_ITEM_GRADED event represents that grading is complete for all units of a return line item within a return package. Examine returns.returnDetails.returnLineItem to determine the grading. Within returnLineItem, GradingSummary shows how many units of the line item have been graded, and the ConditionUnits show the item condition and the count of units in that condition. The condition field has one of the following values:
- A condition of
SELLABLEindicates that the item is in sellable condition. Sellable items are added back to the merchant's inventory to be available for sale. - A condition of
DEFECTIVEindicates that the item is defective and isn't sellable. A defective condition is attributed to reasons that the merchant can control such as manufacturing defects, missing parts, and so on. - A condition of
DAMAGEDindicates that the item is damaged and isn't sellable. A damaged condition is attributed to reasons that the carrier, fulfiller, or customer can control such as damaged packaging, broken seal, damage during transit, and so on. - A condition of
FULFILLMENT_EXPIREDindicates that item grading has been delayed for long enough that the item can no longer be graded.
Step 5: Update your order management system
Finally, update your order management system and downstream systems (such as analytics) to reflect the return details that you retrieved from the response.
By updating the return details in your order management system, your customer service agents can see that a customer successfully initiated a self-service return. Having accurate return details also enables eCommerce managers to see how many customers attempt to return items through the self-service flow with Amazon, so that they can fix any problems customers might have in the return process.
Related topics
Updated 16 days ago