Buy with Prime | Developer Documentation
Documentation

Steps to Cancel Orders

📘

Important

The Buy with Prime API is offered as a preview and might change as we receive feedback and iterate on the interfaces. We are sharing this early documentation to help you learn about the Buy with Prime API as we write and iterate on the content.

A Buy with Prime order cancellation is an action that a shopper, merchant, or merchant-authorized person can take to request cancellation of all Buy with Prime items in a previously placed order.

Note: Requesting order cancellation doesn't guarantee cancellation of the order.

You request a Buy with Prime order cancellation by using the cancelOrder mutation.

Prerequisites

Subscribe to the following Buy with Prime events:

You subscribe and receive notifications for Buy with Prime events through Amazon EventBridge. For details, see Steps to Subscribe to Buy with Prime Events.

Steps to cancel orders

This section describes how to cancel Buy with Prime orders.

  1. Check the fulfillment status of line items.
  2. Request order cancellation.
  3. Check order cancellation status.
  4. Update your order management system.

Step 1: Check the fulfillment status of line items

The ability to successfully cancel an order depends on the fulfillment status of all line items in the order. The fulfillment status of all line items must be PENDING. You therefore must use the order query before you attempt to cancel the order. For an example, see Get line item IDs and package information details.

In the response to the order query, examine the state field of the PackageInformationDetails:

  • If all line items are in the PENDING state, you can submit a Buy with Prime cancellation request. However, submitting a request doesn't guarantee cancellation.
  • If any line item isn't in the PENDING state, Buy with Prime cancellation requests are no longer allowed. If you make a cancellation request for a shipped order, the cancelOrder mutation will return an error.

Step 2: Request order cancellation

If you determined in the previous step that fulfillment for all line items in the order is in the PENDING state, you can attempt to cancel the order. To request order cancellation, call the cancelOrder mutation. For example requests and responses, see Cancel a Buy with Prime Order.

You can set the cancellation reason for a line item to be one of the following values:

  • ORDERED_BY_MISTAKE: The customer made a mistake when placing the order.
  • ITEMS_ARRIVING_LATE: The customer canceled the order because some items wouldn’t arrive on time.
  • INCORRECT_SHIPPING_ADDRESS: The customer used an incorrect shipping address when placing the order
  • OUT_OF_STOCK: The item went out of stock after the order was placed and can't be delivered
  • PAYMENT_ISSUE: There was an issue charging a shopper for the purchase.
  • OTHER: Other. You can add the reason in the note field.

For the definitions of cancellation reasons, see CancellationDetails.

After you call cancelOrder, Buy with Prime sets the cancellation state of the order to be PENDING as it determines whether the order can be cancelled. One of two things happens based on the result:

  • Success: If the order can be cancelled, Buy with Prime cancels the fulfillment request, sets the cancellation state to SUCCESS, initiates a refund request, and sends a REFUND_REQUESTED event to you for processing. For details about refunds, see Steps to Process Refunds.
  • Failure: If the order can't be cancelled (for example, the order has already been shipped), the cancellation request fails, Buy with Prime sets the cancellation state to REJECTED, the call to cancelOrder returns an error.

For the definitions of cancellation states, see CancellationDetails.

Step 3: Check order cancellation status

To see if you can update your order management system or add a "cancel order" button to your site, you can check Buy with Prime order cancellation status in two ways:

Step 4: Update your order management system

Finally, update your order management system and downstream systems to reflect the cancellation details.

Related topics

Updated about 4 hours ago