Update 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.
If you add an external return to a Buy with Prime order, you must update the return details as you process the return. To update the details, call the Buy with Prime updateOrder mutation. Use the updateOrder mutation only to make updates to external returns, not to update returns created by Buy with Prime.
To update an external return, provide a returnIdentifier that is either a Buy with Prime return ID or an alias that you assigned to the return when you added the return to the order. To get this information, you can use the order query to fetch all of the returns associated with the order. For an example, see Get all returns that have been initiated for an order.
To update an external return using a Buy with Prime return ID, provide the returnIdentifier as returns.details.returnIdentifier.id. To update an external return using an alias, provide the returnIdentifier as returns.details.returnIdentifier.aliases. If you use an alias without a returnIdentifier as returns.details.aliases, Buy with Prime considers the request to be a new external return instead of an update to an existing external return.
The following examples show how to update the return details of an order.
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.
Update an external return for a single line item using the Buy with Prime return ID
The following example shows how to use the updateOrder mutation to update an order with the details of an external return.
This example uses the Buy with Prime return ID to identify the return. You can also use an alias to identify the return.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "order-id-1",
returns: {
details: [
returnIdentifier: {
id: 'return-id-1'
}
state: "CANCELLED"
]
}
}
) {
order {
id
returns {
details {
id
createdAt
updatedAt
aliases {
aliasType
aliasId
}
state
returnLineItems {
id
returnFor {
orderLineItemAmounts {
amount
lineItem {
id
amount
}
}
}
}
}
}
}
}
}
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": "CANCELLED",
"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
}
}
}
]
}
],
}
]
}
}
}
}
}
Update an external return for a single line item using an alias
The following example shows how to use the updateOrder mutation to update an order with the details of an external return.
This example uses an alias to identify the return. You can also use the Buy with Prime return ID to identify the return.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "order-id-1",
returns: {
details: [
returnIdentifier: {
"aliases": [
{
"aliasType": "EXTERNAL-RETURN-ID",
"aliasId": "external-return-id-1"
}
]
}
state: "CANCELLED"
]
}
}
) {
order {
id
returns {
details {
id
createdAt
updatedAt
aliases {
aliasType
aliasId
}
state
returnLineItems {
id
returnFor {
orderLineItemAmounts {
amount
lineItem {
id
amount
}
}
}
}
}
}
}
}
}
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": "CANCELLED",
"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
}
}
}
]
}
],
}
]
}
}
}
}
}
Update multiple external returns
The following example shows how to update multiple external returns.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "order-id-1",
returns: {
details: [
{
returnIdentifier: {
id: 'return-id-1'
},
state: "CANCELLED"
},
{
returnIdentifier: {
id: 'return-id-2'
},
state: "CANCELLED"
}
]
}
}
) {
order {
id
returns {
details {
id
createdAt
updatedAt
aliases {
aliasType
aliasId
}
state
returnLineItems {
id
returnFor {
orderLineItemAmounts {
amount
lineItem {
id
amount
}
}
}
}
}
}
}
}
}
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": "CANCELLED",
"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
}
}
}
]
}
],
},
{
"id": "return-id-2",
"createdAt": "2024-08-11T07:37:24.907Z",
"updatedAt": "2024-08-11T07:37:24.907Z",
"state": "CANCELLED",
"aliases": [
{
"aliasType": "EXTERNAL-RETURN-ID",
"aliasId": "external-return-id-2"
}
],
"returnLineItems": [
"id": "return-line-item-1",
"returnFor": {
"orderLineItemAmounts": [
{
"amount": {
"value": 1
},
"lineItem": {
"id: "line-item-id-2",
"amount": {
"value": 1
}
}
}
]
}
],
}
]
}
}
}
}
}
Update the state of an external return to CANCELLED
The following example shows how to update the state of the external return to CANCELLED.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "order-id-1",
returns: {
details: [
{
returnIdentifier: {
alias: {
"aliasType": "EXTERNAL-RETURN-ID",
"aliasId": "external-return-id-1"
}
},
state: "CANCELLED"
}
]
}
}
) {
order {
id
returns {
details {
id
createdAt
updatedAt
aliases {
aliasType
aliasId
}
state
returnLineItems {
id
returnFor {
orderLineItemAmounts {
amount
lineItem {
id
amount
}
}
}
}
}
}
}
}
}
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": "CANCELLED",
"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
}
}
}
]
}
],
}
]
}
}
}
}
}
Update the state of an external return to COMPLETED
The following example shows how to update the state of the external return to COMPLETED.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "order-id-1",
returns: {
details: [
{
returnIdentifier: {
alias: {
"aliasType": "EXTERNAL-RETURN-ID",
"aliasId": "external-return-id-2"
}
},
state: "COMPLETED"
}
]
}
}
) {
order {
id
returns {
details {
id
createdAt
updatedAt
aliases {
aliasType
aliasId
}
state
returnLineItems {
id
returnFor {
orderLineItemAmounts {
amount
lineItem {
id
amount
}
}
}
}
}
}
}
}
}
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": "COMPLETED",
"aliases": [
{
"aliasType": "EXTERNAL-RETURN-ID",
"aliasId": "external-return-id-2"
}
],
"returnLineItems": [
"id": "return-line-item-1",
"returnFor": {
"orderLineItemAmounts": [
{
"amount": {
"value": 1
},
"lineItem": {
"id: "line-item-id-1",
"amount": {
"value": 1
}
}
}
]
}
],
}
]
}
}
}
}
}
Replace external return aliases in a Buy with Prime order
To update external return aliases in a Buy with Prime order, pass a new, complete list of aliases. The new list of aliases will replace the existing list of aliases.
Suppose there is an existing external return with a Buy with Prime return ID of return-id-1 and an external alias with an aliasType of EXTERNAL-RETURN-ID and an alias Id of external-return-id-1.
The following example replaces the aliasId of EXTERNAL-RETURN-ID with external-return-id-2.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "order-id-1",
returns: {
details: [
{
returnIdentifier: {
id: 'return-id-1'
},
aliases: [
{
aliasType: "EXTERNAL-RETURN-ID",
aliasId: "external-return-id-2"
}
]
}
]
}
}
) {
order {
id
returns {
details {
id
createdAt
updatedAt
aliases {
aliasType
aliasId
}
state
returnLineItems {
id
returnFor {
orderLineItemAmounts {
amount
lineItem {
id
amount
}
}
}
}
}
}
}
}
}
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-2"
}
],
"returnLineItems": [
"returnFor": {
"orderLineItemAmounts": [
{
"amount": {
"value": 1
},
"lineItem": {
"id: "line-item-id-1",
"amount": {
"value": 1
}
}
}
]
}
],
}
]
}
}
}
}
}
Add an external return alias to a Buy with Prime order
Suppose there is an existing return with a Buy with Prime return ID of return-id-1 and an alias with an aliasType of EXTERNAL-RETURN-ID and an aliasId of external-return-id-1. The following example appends a DISPLAY-RETURN-ID alias to the alias list.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "order-id-1",
returns: {
details: [
{
returnIdentifier: {
id: 'return-id-1'
},
aliases: [
{
aliasType: "EXTERNAL-RETURN-ID",
aliasId: "external-return-id-1"
},
{
aliasType: "DISPLAY-RETURN-ID",
aliasId: "display-return-id"
}
]
}
]
}
}
) {
order {
id
returns {
details {
id
createdAt
updatedAt
aliases {
aliasType
aliasId
}
state
returnLineItems {
id
returnFor {
orderLineItemAmounts {
amount
lineItem {
id
amount
}
}
}
}
}
}
}
}
}
Response
{
"data": {
"updateOrder": {
"order": {
"id": "order-id-1",
"returns": {
"details": [
{
"id": "return-id-1",
"updatedAt": "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"
},
{
aliasType: "DISPLAY-RETURN-ID",
aliasId: "display-return-id"
}
],
"returnLineItems": [
"returnFor": {
"orderLineItemAmounts": [
{
"amount": {
"value": 1
},
"lineItem": {
"id: "line-item-id-1",
"amount": {
"value": 1
}
}
}
]
}
],
}
]
}
}
}
}
}
Delete an external return alias in a Buy with Prime order
Suppose there is an existing external return with a Buy with Prime return ID of return-id-1 and external alias IDs of external-return-id-1 and display-return-id. The following example shows how to delete the display-return-id alias. Essentially, you're replacing the alias list with a new list that only contains external-return-id-1.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "order-id-1",
returns: {
details: [
{
returnIdentifier: {
id: 'return-id-1',
},
aliases: [
{
aliasType: "EXTERNAL-RETURN-ID",
aliasId: "external-return-id-1"
}
]
}
]
}
}
) {
order {
id
returns {
details {
id
createdAt
updatedAt
aliases {
aliasType
aliasId
}
state
returnLineItems {
id
returnFor {
orderLineItemAmounts {
amount
lineItem {
id
amount
}
}
}
}
}
}
}
}
}
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": [
"returnFor": {
"orderLineItemAmounts": [
{
"amount": {
"value": 1
},
"lineItem": {
"id: "line-item-id-1",
"amount": {
"value": 1
}
}
}
]
}
],
}
]
}
}
}
}
}
Related topics
Updated 1 day ago