Get Return Details
Important
The Buy with Prime API is offered as a preview and might change as we receive feedback and iterate on the interfaces. We are sharing this early documentation to help you learn about the Buy with Prime API as we write and iterate on the content.
To process Buy with Prime returns for an order, you 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 Process Returns. 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(orderId: "example-order-id") {
id
returns {
details {
id
createdAt
updatedAt
state
returnPackageDetails {
id
state
packageTracker {
packageTrackerIdentifier {
trackingNumber
carrierCode
}
estimatedDeliveryDate
latestMilestone {
status {
code
message {
locale,
value
}
}
address
occurredAt
}
milestones {
status {
code
message {
locale,
value
}
}
address
occurredAt
}
trackingUrl
}
returnPackageFor {
orderLineItems {
lineItem {
id
}
returnedQuantity {
amount
}
}
}
returnLineItems {
id
grading {
summary {
gradedAmount {
}
unitWiseCondition {
}
}
}
returnReason {
reasonCode
description {
locale
value
}
comments {
locale
value
}
}
lineItem {
lineItem {
id
}
returnedQuantity {
amount
}
}
}
returnFor {
orderLineItems {
lineItem {
id
}
returnedQuantity {
amount
}
}
}
}
}
}
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",
"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
},
"returnPackageFor": {
"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"
}
]
}
},
"returnReason": {
"reasonCode": "CR-ORDERED_WRONG_ITEM",
"description": {
"locale": "en-US",
"value": "Bought by mistake"
},
"comments": {
"locale": "en-US",
"value": "I wanted another item"
}
},
"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",
"returnPackageDetails": [
{
"id": "example-return-package-id1",
"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
},
"returnPackageFor": {
"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"
}
]
}
},
"returnReason": {
"reasonCode": "CR-ORDERED_WRONG_ITEM",
"description": {
"locale": "en-US",
"value": "Bought by mistake"
},
"comments": {
"locale": "en-US",
"value": "I wanted another item"
}
},
"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",
"returnPackageDetails": [
{
"id": "example-return-package-id2",
"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
},
"returnPackageFor": {
"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"
}
]
}
},
"returnReason": {
"reasonCode": "CR-FOUND_BETTER_PRICE",
"description": {
"locale": "en-US",
"value": "Better price available"
},
"comments": {
"locale": "en-US",
"value": "I wanted another item"
}
},
"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",
"returnPackageDetails": [
{
"id": "example-return-package-id1",
"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
},
"returnPackageFor": {
"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"
}
]
}
},
"returnReason": {
"reasonCode": "CR-ORDERED_WRONG_ITEM",
"description": {
"locale": "en-US",
"value": "Bought by mistake"
},
"comments": {
"locale": "en-US",
"value": "I wanted another item"
}
},
"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",
"returnPackageDetails": [
{
"id": "example-return-package-id",
"state": "CREATED",
"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
},
"returnPackageFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id",
"amount": {
"unit": "ONE",
"value": 1
}
}
}
]
}
}
],
"returnLineItems": [
{
"id": "example-return-line-item-id1",
"returnReason": {
"reasonCode": "CR-ORDERED_WRONG_ITEM",
"description": {
"locale": "en-US",
"value": "Bought by mistake"
},
"comments": {
"locale": "en-US",
"value": "I wanted another item"
}
},
"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 (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",
"returnPackageDetails": [
{
"id": "example-return-package-id",
"state": "IN_TRANSIT",
"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
},
"returnPackageFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id",
"amount": {
"unit": "ONE",
"value": 1
}
}
}
]
}
}
],
"returnLineItems": [
{
"id": "example-return-line-item-id1",
"returnReason": {
"reasonCode": "CR-ORDERED_WRONG_ITEM",
"description": {
"locale": "en-US",
"value": "Bought by mistake"
},
"comments": {
"locale": "en-US",
"value": "I wanted another item"
}
},
"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 (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",
"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
},
"returnPackageFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id",
"amount": {
"unit": "ONE",
"value": 1
}
}
}
]
}
}
],
"returnLineItems": [
{
"id": "example-return-line-item-id1",
"returnReason": {
"reasonCode": "CR-ORDERED_WRONG_ITEM",
"description": {
"locale": "en-US",
"value": "Bought by mistake"
},
"comments": {
"locale": "en-US",
"value": "I wanted another item"
}
},
"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
}
}
]
}
}
]
}
}
}
}
Get refund details for a return
This section contains queries that you can use to get refund details for a return.
Get refund details for a return when return package is IN_TRANSIT
IN_TRANSITThe following example gets refundDetails for a return. The example issues a single refund example-refund-id1 for all items the customer dropped off in the return delivery package example-return-package-id1.
Request
// GraphQL query
query order {
order(orderId: "example-order-id") {
id
returns {
details {
id
returnLineItems {
id
refundDetails {
id
createdAt
updatedAt
refundRequestReason
state
refundTotal {
totalAmount {
amount
currencyCode
}
}
}
}
}
}
}
}
Response
{
"data": {
"order": {
"id": "example-order-id",
"returns": {
"details": [
{
"id": "example-return-id",
"returnLineItems": [
{
"id": "example-return-line-item-id1",
"refundDetails": [
{
"id": "example-refund-id1",
"createdAt": "2024-10-28T13:32:38.339Z",
"updatedAt": "2024-10-28T13:32:38.781Z",
"refundRequestReason": "RETURN_DROPPED_OFF_PICKED_UP",
"state": "SUCCESS",
"refundTotal": {
"totalAmount": {
"amount": 30.00,
"currencyCode": "USD"
}
}
}
]
},
{
"id": "example-return-line-item-id2",
"refundDetails": [
{
"id": "example-refund-id1",
"createdAt": "2024-10-28T13:32:38.339Z",
"updatedAt": "2024-10-28T13:32:38.781Z",
"refundRequestReason": "RETURN_DROPPED_OFF_PICKED_UP",
"state": "SUCCESS",
"refundTotal": {
"totalAmount": {
"amount": 30.00,
"currencyCode": "USD"
}
}
}
]
}
]
}
]
}
}
}
}
Get refund details for a return after the returned item is received
The following example gets refundDetails for a return. The example issues separate refunds example-refund-id1 and example-refund-id2 for each quantity of the returnLineItem after grading of the returned units.
Request
// GraphQL query
query order {
order(orderId: "example-order-id") {
id
returns {
details {
id
returnLineItems {
id
refundDetails {
id
createdAt
updatedAt
refundRequestReason
state
refundTotal {
totalAmount {
amount
currencyCode
}
}
}
}
}
}
}
}
Response
{
"data": {
"order": {
"id": "example-order-id",
"returns": {
"details": [
{
"id": "example-return-id",
"returnLineItems": [
{
"id": "example-return-line-item-id1",
"refundDetails": [
{
"id": "example-refund-id1",
"createdAt": "2024-10-28T13:32:38.339Z",
"updatedAt": "2024-10-28T13:32:38.781Z",
"refundRequestReason": "RETURN_DROPPED_OFF_PICKED_UP",
"state": "SUCCESS",
"refundTotal": {
"totalAmount": {
"amount": 15.00,
"currencyCode": "USD"
}
}
},
{
"id": "example-refund-id1",
"createdAt": "2024-10-28T13:32:38.339Z",
"updatedAt": "2024-10-28T13:32:38.781Z",
"refundRequestReason": "RETURN_DROPPED_OFF_PICKED_UP",
"state": "SUCCESS",
"refundTotal": {
"totalAmount": {
"amount": 15.00,
"currencyCode": "USD"
}
}
}
]
}
]
}
]
}
}
}
}
Related topics
Updated about 15 hours ago