Update Refund 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.
As you process Buy with Prime refunds, you must update the associated Buy with Prime order with the latest information. For a given refund, you typically call the Buy with Prime updateOrder
mutation multiple times. For details, see Steps to Process Refunds.
The following table shows the refund state values that you can set on your next call to updateOrder
given the current refund state. For details about processing refunds, see Steps to Process Refunds.
Current refund state | Allowable states you can use when you update a Buy with Prime refund |
---|---|
PENDING | PENDING , PARTIAL , FAILURE , SUCCESS |
FAILURE | PARTIAL , FAILURE , SUCCESS |
PARTIAL | PARTIAL , SUCCESS |
SUCCESS | SUCCESS |
A refund status reason is the reason that the refund is in the specified state. You specify a refund status reason from a list of pre-defined codes. For a list of refund status reason codes, see RefundStatusReasonInput
. You can call the updateOrder
mutation to update this value if the return reason changes.
You can associate each refund with one or more identifiers called aliases, which are in the refunds.details.aliases
field of the order
. If you use aliases for a refund, it is crucial to ensure that the aliases that you provide for the refund are unique and aren't already associated with other refunds in the order.
Each alias has an aliasId
and an aliasType
. We strongly recommend that you provide a unique aliasId
that you can use when you call the updateOrder
mutation to add or update refund details.
You can add and update refund aliases related to the order by calling the updateOrder
mutation in the following way:
- Updating an alias: Aliases of the same type overwrite each other. Therefore, to update an alias, call the
updateOrder
mutation and provide analiasType
that is already present for the refund. The existingaliasId
with thataliasType
will be overwritten with thealiasId
that you provide in theupdateOrder
request. For example, consider an order with a refundaliasType
ofEXTERNAL-REFUND-ID
and analiasId
ofexternal-refund-id-1
. If you call theupdateOrder
mutation and specify analiasType
ofEXTERNAL-REFUND-ID
and analiasId
ofexternal-refund-id-2
, thealiasId
for theEXTERNAL-REFUND-ID
is overwritten with the new value,external-refund-id-2
. - Adding aliases: To add an alias, call the
updateOrder
mutation and provide analias
with a newaliasType
.
Note
You can't delete existing aliases.
The following examples show how to update the refund details of an order.
Update refund details and set the refund state to PARTIAL
After you initiate a refund payment in your order management system, you must update the Buy with Prime order with the amount that was refunded to the customer. The following example request indicates that $4 of a requested $10 refund has been initiated. For details, see Steps to Process Refunds.
Request
// GraphQL mutation
mutation updateOrder($orderIdentifier: OrderIdentifier!, $input: UpdateOrderInput!) {
order {
id
}
}
// Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"refunds": {
"details": [
{
"id": "refund-123",
"aliases": [
{
"aliasType": "EXTERNAL_REFUND_ID",
"aliasId": "your-oms-refund-id"
}
],
"refundTotal": {
"totalAmount": {
"amount": 4,
"currencyCode": "USD"
}
},
"state": "PARTIAL",
"refundFor": {
"orderLineItems": [
{
"lineItemId": {
"lineItemId": "example-line-item-id"
}
}
]
},
"paymentDetails": [
{
"id": "example-payment-transfer-id-1",
"amount": {
"amount": 4,
"currencyCode": "USD"
},
"paymentMethod": {
"displayString": "Visa ending in 1234",
"type": "AMAZON_PAY"
},
"state": "SUCCESS"
}
]
}
]
}
}
}
Response
{
"data": {
"updateOrder": {
"id": "example-order-id"
}
}
}
Update refund details and set the refund state to SUCCESS
The following sample request updates a refund that was previously $4 with another $6. The request sets the refund state to SUCCESS
because the total refund amount ($10) is complete.
Request
// GraphQL mutation
mutation updateOrder($orderIdentifier: OrderIdentifier!, $input: UpdateOrderInput!) {
order {
id
}
}
// Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"refunds": {
"details": [
{
"id": "refund-123",
"aliases": [
{
"aliasType": "EXTERNAL_REFUND_ID",
"aliasId": "your-oms-refund-id"
}
],
"refundTotal": {
"totalAmount": {
"amount": 10,
"currencyCode": "USD"
}
},
"state": "SUCCESS",
"refundFor": {
"orderLineItems": [
{
"lineItemId": {
"lineItemId": "example-line-item-id"
}
}
]
},
"paymentDetails": [
{
"id": "example-payment-transfer-id-2",
"amount": {
"amount": 6,
"currencyCode": "USD"
},
"paymentMethod": {
"displayString": "Visa ending in 1234",
"type": "AMAZON_PAY"
},
"state": "SUCCESS"
}
]
}
]
}
}
}
Response
{
"data": {
"updateOrder": {
"id": "example-order-id"
}
}
}
Update refund details and set the refund state to REJECTED
In some cases you might need to reject a refund as it might have been already processed or due to fraudulent return attempt. The following sample request rejects a refund. The request sets the refund state to REJECTED
.
Request
// GraphQL mutation
mutation updateOrder($orderIdentifier: OrderIdentifier!, $input: UpdateOrderInput!) {
order {
id
}
}
// Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"refunds": {
"details": [
{
"id": "refund-123",
"aliases": [
{
"aliasType": "EXTERNAL_REFUND_ID",
"aliasId": "your-oms-refund-id"
}
],
"refundTotal": {
"totalAmount": {
"amount": 0,
"currencyCode": "USD"
}
},
"state": "REJECTED"
}
]
}
}
}
Response
{
"data": {
"updateOrder": {
"id": "example-order-id"
}
}
}
Update a refund reason
In some cases, you might need to update the refund request reason or the refund status reason after you submit the initial refund request. This can happen if new information becomes available or the return reason changes.
To update the refund request reason or the refund status reason, include the updated values in a subsequent updateOrder
mutation. The new values will override the previous values.
For example, assume that you initially submitted a refund request with the reason DELIVERED_NOT_RECEIVED
, but the customer later contacts you and explains that the item was actually damaged. The following example shows how to update the refund request reason to DAMAGED_DEFECTIVE_ITEM
.
Request
// GraphQL mutation
mutation updateOrder($orderIdentifier: OrderIdentifier!, $input: UpdateOrderInput!) {
order {
id
}
}
// Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"refunds": {
"details": [
{
"id": "refund-123",
"refundRequestReason": "DAMAGED_DEFECTIVE_ITEM"
}
]
}
}
}
Response
{
"data": {
"updateOrder": {
"id": "example-order-id"
}
}
}
Similarly, if the initial refund request was approved but then later needs to be rejected due to a fraudulent return attempt, you can update the refund state and status reason as the following example shows.
Request
// GraphQL mutation
mutation updateOrder($orderIdentifier: OrderIdentifier!, $input: UpdateOrderInput!) {
order {
id
}
}
// Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"refunds": {
"details": [
{
"id": "refund-123",
"state": "REJECTED",
"refundStatusReason": "FRAUDULENT_RETURN_ATTEMPT"
}
]
}
}
}
Response
{
"data": {
"updateOrder": {
"id": "example-order-id"
}
}
}
Related topics
Updated 4 days ago