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.
The way you handle a return depends on whether the return was requested through Buy with Prime or through your system (an external return):
- Returns requested through Buy with Prime: You are notified of these returns through return events. In this case, you handle return events and update returns in the Buy with Prime order with the latest details.
- External returns: The associated Buy with Prime order initially has no record of these returns. In this case, you add a return to the Buy with Prime order after you issue the return to the customer. If there are further updates to the return on your end, you can update returns in the Buy with Prime order with the latest details.
This topic describes how to add external returns and handle Buy with Prime return events.
Steps to add an external return
If a return is requested externally to Buy with Prime, take the following steps to add the return to the Buy with Prime order. Before you do these steps, you must initiate an external return for the order. You must also have a unique identifier associated with the external return.
Step 1: Add the return to the Buy with Prime order
After you have the unique identifier associated with the external return, use the updateOrder mutation to add the return to the Buy with Prime order. The following example shows a request and response. For additional examples, see Add an External Return.
Note that in the request:
- There is no Buy with Prime return ID (
returns.details.id), because Buy with Prime doesn't have a record of the return yet. - We highly recommend that you provide a unique
aliasfor the return. Eachaliashas analiasTypeand analiasId. Ensure that thealiasIdthat you provide is unique and not already associated with other returns present in the order. - You can set the return state to
CREATEDorCOMPLETED.
A successful response provides a Buy with Prime return ID in returns.details.id, indicating that the return was successfully added to the Buy with Prime order.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
orderIdentifier: {
orderId: "123-4567-8910"
}
input: {
returns: {
details: [
{
aliases: [
{
aliasType: "EXTERNAL-RETURN-ID",
aliasId: "external-return-id-1"
}
],
state: "CREATED",
returnLineItems: [
{
returnFor: {
orderLineItemAmounts: [
{
amount: {
value: 1
},
lineItemId: {
id: "line-item-id-1"
}
}
]
}
}
]
}
]
}
}
) {
order {
id
returns {
details {
id
createdAt
updatedAt
aliases {
aliasType
aliasId
}
state
returnLineItems {
id
returnFor {
orderLineItemAmounts {
amount {
value
}
lineItem {
id
amount {
value
}
}
}
}
}
}
}
}
}
}
Response
{
"data": {
"updateOrder": {
"order": {
"id": "order-id-1",
"returns": {
"details": [
{
"id": "return-id-1",
"createdAt": "2024-08-11T07:37:24.907Z",
"updatedAt": "2024-08-11T07:37:24.907Z",
"state": "CREATED",
"aliases": [
{
"aliasType": "EXTERNAL-RETURN-ID",
"aliasId": "external-return-id-1"
}
],
"returnLineItems": [
"id": "return-line-item-1",
"returnFor": {
"orderLineItemAmounts": [
{
"amount": {
"value": 1
},
"lineItem": {
"id": "line-item-id-1",
"amount": {
"value": 1
}
}
}
]
}
],
}
]
}
}
}
}
}
Step 2: Update the Buy with Prime order with return details
As you process the return in your order management system, you must update the Buy with Prime order with the latest return details. To update the return details in the Buy with Prime order, call the updateOrder mutation. For details, see Steps to update returns.
To identify the external return to the updateOrder mutation, you can use one of the following IDs:
- The
aliasIdthat you specified when you added the return to the order. - The return ID that the
updateOrdermutation returned inreturns.details.idwhen you added the return to the order.
Steps to handle return events
This section describes how to process Buy with Prime returns. The starting point for processing a return is when you receive a return event. 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.
To handle return events, take the following steps:
- Subscribe to return events.
- 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: Subscribe to return events
Subscribe to the following Buy with Prime events:
RETURN_STARTEDRETURN_PACKAGE_IN_TRANSITRETURN_PACKAGE_DELIVEREDRETURN_PACKAGE_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.
Step 2: 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 3: Query the order
Call the order query to get the return details for that order. For an example request and response, see Get return details for an order.
Step 4: 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",
"returnPackageDetails": [
{
"id": "example-return-package-id",
"state": "COMPLETED",
"packageTracker": {
"packageTrackerIdentifier": {
"trackingNumber": "Santos858aea9fb7a647269239fdb16cc5a538",
"carrierCode": "ups"
},
"estimatedDeliveryDate": null,
"latestMilestone": {
"status": {
"code": "PENDING",
"message": {
"locale": "en-US",
"value": "Delivery tracking information is not available yet."
}
},
"address": null,
"occurredAt": "2024-11-14T11:42:37.516Z"
},
"milestones": [
{
"status": {
"code": "PENDING",
"message": {
"locale": "en-US",
"value": "Delivery tracking information is not available yet."
}
},
"address": null,
"occurredAt": "2024-11-14T11:42:37.516Z"
}
],
"trackingUrl": null
},
"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 5: 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_PACKAGE_IN_TRANSIT and RETURN_PACKAGE_DELIVERED events are related to the return package. To determine the current status of the return package, examine the state field in the returnPackageDetails . 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 returnPackageDetails also contains details such as the tracking ID, carrier code, and return reason.
The return reason contains the details of why the shopper returned the item. It has a reason code, description, and shopper comments (free-form text captured during return creation). The Buy with Prime API has a default set of reason code values, which the shopper selects during return creation. The reason description contains a displayable message for the return reason, which can change to improve the shopper return experience. Reason code values are fixed, whereas description strings are dynamic and shouldn't be parsed. For a list of default return reason codes, see Return reason 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 6: 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.
For a list of default return reason codes, see Return reason code.
Steps to update returns
If you add an external return to a Buy with Prime order, you must update the Buy with Prime order to reflect any updates that you make to the return on your end. By updating the Buy with Prime order with the latest details, you enable return details to display correctly to the customer when they check their order using the online returns center.
To update a return, take the following steps:
Step 1: Update the return details
To update the external return details in the Buy with Prime order, call the updateOrder mutation.
To identify the external return to the updateOrder mutation, you can use one of the following IDs:
- The
aliasIdthat you specified when you added the return to the order. - The Buy with Prime return ID that the
updateOrdermutation returned inreturns.details.idwhen you added the return to the order.
Currently, you can only update the following details of an external refund:
- Return state: You can set the return state to
CREATED,CANCELLED, orCOMPLETED. - Aliases: To update external return aliases in a Buy with Prime order, you pass a new, complete list of aliases. The new list of aliases will replace the existing list of aliases. To delete all of the aliases, pass an empty alias list.
For example requests and responses, see Update Return Details.
Related topics
Updated 2 days ago