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 stateAllowable states you can use when you update a Buy with Prime refund
PENDINGPENDING, PARTIAL, FAILURE, SUCCESS
FAILUREPARTIAL, FAILURE, SUCCESS
PARTIALPARTIAL, SUCCESS
SUCCESSSUCCESS

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 an aliasType that is already present for the refund. The existing aliasId with that aliasType will be overwritten with the aliasId that you provide in the updateOrder request. For example, consider an order with a refund aliasType of EXTERNAL-REFUND-ID and an aliasId of external-refund-id-1. If you call the updateOrder mutation and specify an aliasType of EXTERNAL-REFUND-ID and an aliasId of external-refund-id-2, the aliasId for the EXTERNAL-REFUND-ID is overwritten with the new value, external-refund-id-2.
  • Adding aliases: To add an alias, call the updateOrder mutation and provide an alias with a new aliasType.

📘

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


Did this page help you?