📘

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.

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. Click the diagram to enlarge it.

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

• Refund Interface
• Refund Interface Examples
• Steps to Process Refunds