Add an External Return
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.
Returns that are requested outside of Buy with Prime (such as when a shopper contacts you directly for a return) are called external returns.
Buy with Prime orders initially have no record of external returns related to the order. Therefore, after you create an external return in your system, you must call the updateOrder mutation to add the information to the associated Buy with Prime order. A successful call adds a return to the Buy with Prime order and returns a Buy with Prime return ID.
The following examples show how to add an external return to an order.
Note
If you want to verify or update or he return later, you can find the return by using the
orderquery to fetch all of the returns associated with the order. For an example, see Get all returns that have been initiated for an order.
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.
Add an external return for a single line item
After you create a return is externally, use the updateOrder mutation to add the details of the return to the Buy with Prime order.
The following example shows a request and response to add an external return that has one line item.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
id: {
orderId: "order-id-1"
}
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
}
}
}
]
}
],
}
]
}
}
}
}
}
Add an external return for multiple line items
The following example shows how to use the updateOrder mutation to add multiple return line item inputs in a single return.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "order-id-1",
returns: {
details: [
{
aliases: [
{
aliasType: "EXTERNAL-RETURN-ID",
aliasId: "external-return-id-1"
}
],
state: "CREATED",
returnLineItems: [
{
returnFor: {
orderLineItemAmounts: [
{
amount: {
value: 1
},
lineItem: {
id: "line-item-id-1",
amount: {
value: 1
}
}
},
{
amount: {
value: 1
},
lineItem: {
id: "line-item-id-2",
amount: {
value: 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
}
}
},
{
amount: {
value: 1
},
lineItem: {
id: "line-item-id-2",
amount: {
value: 1
}
}
}
]
}
}
]
}
]
}
}
}
}
}
Add multiple external returns
The following example shows how to use the updateOrder mutation to add multiple returns to a Buy with Prime order.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "order-id-1",
returns: {
details: [
{
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
}
}
}
]
}
]
},
{
aliases: [
{
aliasType: "EXTERNAL-RETURN-ID",
aliasId: "external-return-id-2"
}
],
state: "CREATED",
returnLineItems: [
returnFor: {
orderLineItemAmounts: [
{
amount: {
value: 1
},
lineItem: {
id: "line-item-id-2",
amount: {
value: 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": [
"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": "CREATED",
"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
}
}
}
]
}
],
}
]
}
}
}
}
}
Add an external return without an alias
The following example shows how to add an externally created return without an alias.
Request
// GraphQL mutation
mutation updateOrder {
updateOrder(
input: {
orderId: "order-id-1",
returns: {
details: [
{
state: "COMPLETED",
returnLineItems: [
returnFor: {
orderLineItemAmounts: [
{
amount: {
value: 1
},
lineItem: {
id: "line-item-id-1",
amount: {
value: 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": "COMPLETED",
"alaises": null,
"returnLineItems": [
"id": "return-line-item-1",
"returnFor": {
"orderLineItemAmounts": [
{
"amount": {
"value": 1
},
"lineItem": {
"id: "line-item-id-1",
"amount": {
"value": 1
}
}
}
]
}
],
}
]
}
}
}
}
}
Related topics
Updated about 4 hours ago