Change the State of a Return Package in the Sandbox
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.
In the sandbox environment, you call the mutation updateOrderReturns to move a return package through various states to publish events without making real-world changes. For example, you can test how your application handles a RETURN_PACKAGE_DELIVERED event without actually delivering and then returning a package by setting the return package state to DELIVERED.
The response to updateOrderReturns contains the current order. Query the order for the updated details.
Reference: updateOrderReturns
updateOrderReturnsIn the sandbox environment, you can make the following state transitions to returns by calling updateOrderReturns.
| Input argument | Current state | Next state | Expected events |
|---|---|---|---|
ReturnDeliveryDetails | CREATED | IN_TRANSIT | RETURN_PACKAGE_IN_TRANSIT |
ReturnDeliveryDetails | CREATED | DROPPED_OFF (for returns marked as No box or label needed) | REFUND_REQUESTED |
ReturnDeliveryDetails | DROPPED_OFF | IN_TRANSIT | RETURN_PACKAGE_IN_TRANSIT |
ReturnDeliveryDetails | IN_TRANSIT | DELIVERED | RETURN_PACKAGE_DELIVERED, REFUND_REQUESTED |
ReturnDeliveryDetails | IN_TRANSIT | FAILED | |
ReturnDeliveryDetails | FAILED,DELIVERED | None, this is a terminal state. | |
ReturnLineItem | grading: any update | RETURN_ITEM_GRADED |
Query the order
Use the following query to get relevant ReturnDetails from the order.
Request
query order($orderIdentifier: OrderIdentifierInput!) {
order(orderIdentifier: $orderIdentifier) {
returns {
details {
id
state
returnDeliveryDetails {
id
state
reason
returnDeliveryFor {
orderLineItemAmounts {
amount {
unit
value
}
lineItem {
id
}
}
}
}
returnLineItems {
id
grading {
summary {
gradedAmount {
unit
value
}
unitWiseCondition {
amount {
unit
value
}
condition
}
}
}
}
}
}
}
}
//Query variables
{
"orderIdentifier": {
"orderId": "example-order-id"
}
}
Prerequisites
- Create a Buy with Prime Order.
- Trigger fulfillment by doing one of the following:
- In the
createOrdercall, set thedesiredExecutionStateasSTARTED. - Trigger fulfillment for an existing order.
- In the
- Update all of the packages in the order to
DELIVERED. For details, see Update multiple packages as DELIVERED. - Using the Merchant Online Return Center, create a return for all or some of the items. For details, see Create returns on behalf of customer.
Examples
Update a return package as DROPPED_OFF
DROPPED_OFFEvents published: REFUND_REQUESTED
For a return package marked as No box or label needed, the following example shows how to move the return package from the initial CREATED state to DROPPED_OFF.
Request
mutation updateOrderReturns($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderReturnsInput!) {
updateOrderReturns(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"returns": {
"details": [
{
"returnIdentifier": {
"id": "example-return-details-id"
},
"returnPackageDetails": [
{
"id": "example-return-package-details-id",
"state": "DROPPED_OFF"
}
]
}
]
}
}
}
Response
{
"data": {
"updateOrderReturns": {
"order": {
"id": "example-order-id"
}
}
}
}
After you see the expected event, Query the order to view the updated details.
Query order response
{
"data": {
"order": {
"returns": {
"details": [
{
"id": "example-return-details-id",
"state": "CREATED",
"returnDeliveryDetails": [
{
"id": "example-return-delivery-details-id",
"state": "DROPPED_OFF",
"returnDeliveryFor": {
"orderLineItemAmounts": [
{
"amount": {
"unit": "ONE",
"value": 1
},
"lineItem": {
"id": "example-line-item-id"
}
}
]
}
}
],
"returnLineItems": [
{
"id": "example-return-line-item-id"
}
]
}
]
}
}
}
}
Update a return package as IN_TRANSIT
Events published: RETURN_PACKAGE_IN_TRANSIT
The following example shows how to move either of the following types of packages to IN_TRANSIT:
- For a return package that isn't marked as No box or label needed, the example moves the return package from
CREATEDtoIN_TRANSIT. - For a return package marked as No box or label needed, the example moves the return package from
DROPPED_OFFtoIN_TRANSIT.
Request
mutation updateOrderReturns($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderReturnsInput!) {
updateOrderReturns(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"returns": {
"details": [
{
"returnIdentifier": {
"id": "example-return-details-id"
},
"returnPackageDetails": [
{
"id": "example-return-package-details-id",
"state": "IN_TRANSIT"
}
]
}
]
}
}
}
Response
{
"data": {
"updateOrderReturns": {
"order": {
"id": "example-order-id"
}
}
}
}
After you see the expected event, Query the order to view the updated details.
Query order response
{
"data": {
"order": {
"returns": {
"details": [
{
"id": "example-return-details-id",
"state": "CREATED",
"returnDeliveryDetails": [
{
"id": "example-return-delivery-details-id",
"state": "IN_TRANSIT",
"returnDeliveryFor": {
"orderLineItemAmounts": [
{
"amount": {
"unit": "ONE",
"value": 1
},
"lineItem": {
"id": "example-line-item-id"
}
}
]
}
}
],
"returnLineItems": [
{
"id": "example-return-line-item-id"
}
]
}
]
}
}
}
}
Update a return package as DELIVERED
DELIVEREDEvents published: RETURN_PACKAGE_DELIVERED. For returns that don't use a drop-off location, REFUND_REQUESTED is also published.
The following example shows how to update a return package from IN_TRANSIT to DELIVERED.
Request
mutation updateOrderReturns($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderReturnsInput!) {
updateOrderReturns(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"returns": {
"details": [
{
"returnIdentifier": {
"id": "example-return-details-id"
},
"returnPackageDetails": [
{
"id": "example-return-package-details-id",
"state": "DELIVERED"
}
]
}
]
}
}
}
Response
{
"data": {
"updateOrderReturns": {
"order": {
"id": "example-order-id"
}
}
}
}
After you see the expected event, Query the order to view the updated details.
Query order response
{
"data": {
"order": {
"returns": {
"details": [
{
"id": "example-return-details-id",
"state": "CREATED",
"returnDeliveryDetails": [
{
"id": "example-return-delivery-details-id",
"state": "DELIVERED",
"returnDeliveryFor": {
"orderLineItemAmounts": [
{
"amount": {
"unit": "ONE",
"value": 1
},
"lineItem": {
"id": "example-line-item-id"
}
}
]
}
}
],
"returnLineItems": [
{
"id": "example-return-line-item-id"
}
]
}
]
}
}
}
}
Update a return package as FAILED
FAILEDEvents published: RETURN_PACKAGE_DELIVERY_FAILED
The following example shows how to mimic an unsuccessful delivery by updating a return package in IN_TRANSIT to FAILED. The reason is set to UNDELIVERABLE by default.
Request
mutation updateOrderReturns($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderReturnsInput!) {
updateOrderReturns(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"returns": {
"details": [
{
"returnIdentifier": {
"id": "example-return-details-id"
},
"returnPackageDetails": [
{
"id": "example-return-package-details-id",
"state": "FAILED"
}
]
}
]
}
}
}
Response
{
"data": {
"updateOrderReturns": {
"order": {
"id": "example-order-id"
}
}
}
}
After you see the expected event, Query the order to view the updated details.
Query order response
{
"data": {
"order": {
"returns": {
"details": [
{
"id": "example-return-details-id",
"state": "CREATED",
"returnDeliveryDetails": [
{
"id": "example-return-delivery-details-id",
"state": "FAILED",
"reason": "UNDELIVERABLE",
"returnDeliveryFor": {
"orderLineItemAmounts": [
{
"amount": {
"unit": "ONE",
"value": 1
},
"lineItem": {
"id": "example-line-item-id"
}
}
]
}
}
],
"returnLineItems": [
{
"id": "example-return-line-item-id"
}
]
}
]
}
}
}
}
Update return line item grading details
Events published: RETURN_ITEM_GRADED. RETURN_COMPLETED is also published if all return packages are updated to DELIVERED and all return line item grading details are updated.
The following example shows how to update the grading details for return line items for a return package in the DELIVERED state.
Request
mutation updateOrderReturns($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderReturnsInput!) {
updateOrderReturns(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"returns": {
"details": [
{
"returnIdentifier": {
"id": "example-return-details-id"
},
"returnLineItems": [
{
"id": "example-return-line-item-id",
"grading": {
"gradingSummary": {
"unitWiseCondition": [
{
"condition": "SELLABLE",
"amount": {
"value": "1"
}
}
]
}
}
}
]
}
]
}
}
}
Response
{
"data": {
"updateOrderReturns": {
"order": {
"id": "example-order-id"
}
}
}
}
After you see the expected event, Query the order to view the updated details.
Query order response
{
"data": {
"order": {
"returns": {
"details": [
{
"id": "example-return-details-id",
"state": "COMPLETED",
"returnDeliveryDetails": [
{
"id": "example-return-delivery-details-id",
"state": "DELIVERED",
"returnDeliveryFor": {
"orderLineItemAmounts": [
{
"amount": {
"unit": "ONE",
"value": 1
},
"lineItem": {
"id": "example-line-item-id"
}
}
]
}
}
],
"returnLineItems": [
{
"id": "example-return-line-item-id",
"grading": {
"summary" : {
"gradedAmount" : {
"unit" : "ONE",
"value" : 1.0
},
"unitWiseCondition" : [
{
"amount": {
"unit" : "ONE",
"value" : 1.0
},
"condition": "SELLABLE"
}
]
}
}
}
]
}
]
}
}
}
}
Updated 2 months ago