Get Return Details
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.
To process Buy with Prime returns for an order, you query the Buy with Prime Return Interface to get details about all the returns associated with the order. For example, you get return information in the following cases:
- To display return information on order pages: By showing the number of items returned for an order, customers have visibility into their return requests.
- To update the status in your order management system when a customer requests a return through Buy with Prime: You can use this information to maintain accurate logs, ensure balances, meet accounting requirements, and conduct analytics and reporting for business performance analysis.
- To help customer service agents help customers: By retrieving return information, customer service agents can confirm that a customer has successfully initiated a self-service return.
The following examples show how to get information about Buy with Prime returns.
For an overview of return terminology, see Return Interface. To learn how to call the Buy with Prime API, see Call the Buy with Prime API.
Get return details for an order
After you receive a return event, you typically query the associated order to get information about any returns that are associated with the order.
Customers can initiate return requests for individual items within an order, so each order can have multiple returns created for it. The following example queries an order to get all the returns that were initiated by a customer for that order, and what the response might look like for different numbers of returns.
Request
// GraphQL query
query order {
order(orderIdentifier: { orderId: "example-order-id" }) {
id
returns {
details {
id
createdAt
updatedAt
state
returnDeliveryDetails {
id
state
reason
trackingDetails {
trackingId
carrierCode
}
returnDeliveryFor {
orderLineItems {
lineItem {
id
}
amount {
value
}
}
}
}
returnLineItems {
id
grading {
summary {
gradedAmount {
value
}
unitWiseCondition {
amount {
value
}
condition
}
}
}
lineItem {
lineItem {
id
}
amount {
value
}
}
}
returnFor {
orderLineItems {
lineItem {
id
}
amount {
value
}
}
}
}
}
}
}
Response (Customer returned a single item)
{
"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"
}
]
}
},
"lineItem": {
"amount": {
"unit": "ONE",
"value": 1
},
"lineItem": {
"id": "example-line-item-id"
}
}
}
],
"returnFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
}
}
]
}
}
}
}
Response (Customer made multiple return requests for the same order)
{
"data": {
"order": {
"id": "example-order-id",
"lineItems": [
{
"id": "example-line-item-id1",
"createdAt": "2024-05-28T20:18:55.196Z"
}
],
"returns": {
"details": [
{
"id": "example-return-id1",
"createdAt": "2024-05-28T20:22:22.512677135Z",
"updatedAt": "2024-05-28T20:22:22.512677135Z",
"state": "COMPLETED",
"returnDeliveryDetails": [
{
"id": "example-return-package-id1",
"state": "COMPLETED",
"trackingDetails": {
"trackingId": "example-tracking-id",
"carrierCode": "UPS"
},
"returnDeliveryFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id1",
"amount": {
"unit": "ONE",
"value": 1
}
}
}
]
}
}
],
"returnLineItems": [
{
"id": "example-return-line-item-id1",
"grading": {
"summary": {
"gradedAmount": {
"unit": "ONE",
"value": 1
},
"unitWiseCondition": [
{
"amount": {
"unit": "ONE",
"value": 1
},
"condition": "Sellable"
}
]
}
},
"lineItem": {
"amount": {
"unit": "ONE",
"value": 1
},
"lineItem": {
"id": "example-line-item-id1"
}
}
}
],
"returnFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id1"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
}
},
{
"id": "example-return-id2",
"createdAt": "2024-05-28T20:23:40.499512584Z",
"updatedAt": "2024-05-28T20:23:40.499512584Z",
"state": "COMPLETED",
"returnDeliveryDetails": [
{
"id": "example-return-package-id2",
"state": "COMPLETED",
"trackingDetails": {
"trackingId": "example-tracking-id",
"carrierCode": "UPS"
},
"returnDeliveryFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id1",
"amount": {
"unit": "ONE",
"value": 2
}
}
}
]
}
}
],
"returnLineItems": [
{
"id": "example-return-line-item-id2",
"grading": {
"summary": {
"gradedAmount": {
"unit": "ONE",
"value": 1
},
"unitWiseCondition": [
{
"amount": {
"unit": "ONE",
"value": 1
},
"condition": "Sellable"
}
]
}
},
"lineItem": {
"amount": {
"unit": "ONE",
"value": 2
},
"lineItem": {
"id": "example-line-item-id1",
"amount": {
"unit": "ONE",
"value": 2
}
}
}
}
],
"returnFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id1"
},
"amount": {
"unit": "ONE",
"value": 2
}
}
]
}
}
]
}
}
}
}
Response (Customer made a single return request for multiple items in the order)
{
"data": {
"order": {
"id": "example-order-id",
"lineItems": [
{
"id": "example-line-item-id1",
"createdAt": "2024-05-28T20:18:55.196Z"
},
{
"id": "example-line-item-id2",
"createdAt": "2024-05-28T20:18:55.196Z"
}
],
"returns": {
"details": [
{
"id": "example-return-id1",
"createdAt": "2024-05-28T20:22:22.512677135Z",
"updatedAt": "2024-05-28T20:22:22.512677135Z",
"state": "COMPLETED",
"returnDeliveryDetails": [
{
"id": "example-return-package-id1",
"state": "COMPLETED",
"trackingDetails": {
"trackingId": "example-tracking-id",
"carrierCode": "UPS"
},
"returnDeliveryFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id2",
"amount": {
"unit": "ONE",
"value": 2
}
}
}
]
}
}
],
"returnLineItems": [
{
"id": "example-return-line-item-id1",
"grading": {
"summary": {
"gradedAmount": {
"unit": "ONE",
"value": 1
},
"unitWiseCondition": [
{
"amount": {
"unit": "ONE",
"value": 1
},
"condition": "Sellable"
}
]
}
},
"lineItem": {
"amount": {
"unit": "ONE",
"value": 2
},
"lineItem": {
"id": "example-line-item-id2"
}
}
}
],
"returnFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id2"
},
"amount": {
"unit": "ONE",
"value": 2
}
}
]
}
}
]
}
}
}
}
Response (Customer didn't request any returns for the order)
{
"data": {
"order": {
"id": "example-order-id"
}
}
}
Response (Return package is yet to be dropped off)
{
"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": "CREATED",
"returnDeliveryDetails": [
{
"id": "example-return-package-id",
"state": "CREATED",
"trackingDetails": {
"trackingId": "example-tracking-id",
"carrierCode": "UPS"
},
"returnDeliveryFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id",
"amount": {
"unit": "ONE",
"value": 1
}
}
}
]
}
}
],
"returnLineItems": [],
"returnFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
}
}
]
}
}
}
}
Response (Return package is IN_TRANSIT)
{
"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": "CREATED",
"returnDeliveryDetails": [
{
"id": "example-return-package-id",
"state": "IN_TRANSIT",
"trackingDetails": {
"trackingId": "example-tracking-id",
"carrierCode": "UPS"
},
"returnDeliveryFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id",
"amount": {
"unit": "ONE",
"value": 1
}
}
}
]
}
}
],
"returnLineItems": [],
"returnFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
}
}
]
}
}
}
}
Response (Return package is DELIVERED)
{
"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": "CREATED",
"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": [],
"returnFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
}
}
]
}
}
}
}
Related topics
Updated 23 days ago