Buy with Prime | Developer Documentation
Documentation
GraphQL Playground

Troubleshoot Refund Errors

📘

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.

Sign Up

This topic explains possible errors that you can encounter when you update an order's refund information by using the updateOrder mutation.

Errors updating refunds

When you update a refund by using the updateOrder mutation, you provide information in the refunds field. You might encounter the following errors associated with this field.

Error Type
Error Code
DescriptionSuggested Action
ValidationErrorDuplicateAliasIdYou attempted to add or update multiple refunds within the same request, and one or more refunds have the same aliasId.Ensure that the aliasId that you provide for refunds are unique.
ValidationErrorDuplicateRefundIdYou provided the same refund ID multiple times in the RefundInput .Update a given refund only once in a single API call.
ValidationErrorInvalidAliasIdThe provided aliasId is already associated with another refund for the same order.Ensure that the aliases you provide for a refund aren't already associated with other refunds present in the order.
ValidationErrorInvalidRefundIdThe provided Buy with Prime refund ID doesn't match any refund IDs for the specified order.Provide a valid Buy with Prime refund ID. To find the refund IDs associated with an order, call the order query. For details, see Query a Buy with Prime Order.
ValidationError
InvalidRefundRequestReasonUpdate
You can only update the refund request reason for external refunds.In the updateOrder mutation, from the refunds field, remove the refundRequestReason field.
ValidationError
InvalidRefundStateTransition
The existing refund state can't transition to the state that you provided in the refunds.details.state field of the updateOrder mutation.Provide a valid refund state. For details about how to process refunds, see Steps to Process Refunds.

External refund synchronization issues

When you use the updateOrder mutation to add an external refund to a Buy with Prime order, Buy with Prime always accepts the refund based on the refund details that you provide in the request.

This means that there can be scenarios in which the external refund details that you provide in the updateOrder mutation conflict with ongoing refunds that are requested through Buy with Prime and vice versa.

In these cases, it is essential to handle the conflicting scenarios appropriately to maintain data consistency between the Buy with Prime order and your order management systems.

Synchronization scenario 1

In this scenario, you use the updateOrder mutation to add an external refund to an order. You later receive the REFUND_REQUESTED event for the same line item.

In these cases, call the updateOrder mutation to update the refund associated with the REFUND_REQUESTED event with the following details:

  • Set the refund state to FAILED.
  • Set the refund amount to 0 (zero).

Synchronization scenario 2

In this scenario, there are two line items in the order:

  • external-line-item-id-1 with a quantity of 1.
  • external-line-item-id-2 with a quantity of 2.

Consider the following sequence of events:

  1. Buy with Prime sends the REFUND_REQUESTED event to request a refund for all the line items in the order. Let’s call this bwp_refund.
  2. You didn't receive this event in time so you process a refund for external-line-item-id-2 for a quantity of 1. Let’s call this external_refund.
  3. You then call updateOrder to add external_refund to the order.
    Even though external-line-item-id-2 is already included in the bwp_refund, Buy with Prime doesn't reject the updateOrder request. Buy with Prime therefore records the external_refund in its system.
  4. After you successfully call updateOrder to add external_refund to the order, you receive the REFUND_REQUESTED event for bwp_refund.

The following diagram shows this scenario. Choose the diagram to enlarge it.

External Refund Synchronization

External Refund Synchronization

To handle the REFUND_REQUESTED event in this case, take the following steps:

  1. Update the bwp_refund associated with the REFUND_REQUESTED event with the following details:
    • Set the refund state to FAILED.
    • Set the refund amount to $0.
  2. On your end, process another refund for the remaining line items (for example, external-line-item-id-1 and external-line-item-id-2 for a quantity of 1 each). Let’s call this external_refund_2.
  3. Make another updateOrder request to add external_refund_2 to the order.
    After the updateOrder request for external_refund_2 is successful, the Buy with Prime order and your order management system are consistent.

Payment issues

In some cases, you might receive a REFUND_REQUESTED event but there is no payment captured for the corresponding order. This scenario can occur for various reasons, such as a failed payment attempt or a canceled order before the payment capture.

In these cases, you should update the refund associated with the REFUND_REQUESTED event with the following details:

  • Set the refund state to FAILED.
  • Set the refund amount to $0.

Related topics

Updated 3 months ago