Buy with Prime | Developer Documentation
Documentation

Synchronize Refunds

📘

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

A Buy with Prime refund is a process by which a customer is reimbursed for an item that they ordered, which is then returned or cancelled.

The Buy with Prime refund event notifies you when to issue a refund; you receive and handle the event. For details about how to subscribe to Buy with Prime events, see Steps to Subscribe to Buy with Prime Events.

This topic outlines terminology and Buy with Prime API operations that you use to manage Buy with Prime refunds.

Terminology

The following sections describe terminology related to refunds.

Refund

A Buy with Prime refund is a process by which a customer is reimbursed for an item that they ordered, which is then returned or cancelled.

A refund for Buy with Prime items in an order is requested in the following cases:

  • After placing an order, a customer goes to the Buy with Prime shopper order details page, where they request to cancel the order.
  • After receiving the order, a customer requests a return for the Buy with Prime items in the order.
  • You use the Buy with Prime merchant console to request an order cancellation or a return on behalf of a customer.
  • After a customer creates an order, the order or an item in the order is cancelled because an item becomes unfulfillable or encounters delivery exceptions such as package undelivered, lost, and so on.

If you subscribe to Buy with Prime events, you're notified of refunds by the REFUND_REQUESTED event. You then initiate the refund and update Buy with Prime with the latest details. For the process, see Steps to Process Refunds.

You currently can't do the following operations with Buy with Prime refunds:

  • Directly generate a Buy with Prime refund request.
  • Update a refund that is not requested through Buy with Prime.
  • Update the items associated with a refund requested through Buy with Prime.
  • Manually generate a refund from the Buy with Prime merchant console. However, you can return or cancel an order from the merchant console. These actions automatically generate a refund request for the order.

Refund state

The state of the refund. As you process refunds with your order management system, you call the updateOrder mutation to update the refund state for the Buy with Prime order. The following table shows the allowable 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
Return

A Buy with Prime return is an action that a customer takes to return previously-delivered items that they purchased in a Buy with Prime order.

For details, see Process Returns.

Reversal

Reversal is a term that the Buy with Prime API uses to encompass the concepts of returns, refunds, and cancellations.

API operations

You use the following mutations, queries, and events to synchronize refunds.

Mutations

NameDescription
updateOrderUpdates an existing Buy with Prime order. As you process refunds, you use this mutation to update the Buy with Prime order with the latest refund details, such as the refund state, the amount you refunded the customer, and so on. For details, see Steps to Process Refunds and Update Refund Details.

Queries

NameDescription
generateReversalOffersProvides a reversal offer for a given Buy with Prime product. For examples, see Get Reversal Offers.
orderGets a Buy with Prime order, in which you can see the refunds associated with an order. With this information, you know the amount of refund requested and for which items to issue a refund. For details, see Steps to Process Refunds and Get Refund Details.

Events

EventWhen Event is Published
REFUND_REQUESTEDRepresents a request to issue a refund for one or more Buy with Prime items. You react to this event by issuing a refund and then updating the Buy with Prime order with the latest refund information. For details, see Steps to Process Refunds.

Related topics

Updated 3 days ago