Cancel a Buy with Prime Order

📘

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.

A Buy with Prime order cancellation is an action that a shopper or merchant can take to request cancellation of all Buy with Prime items in a previously placed order. Requesting order cancellation doesn't guarantee that the order is canceled. 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.

Step 1: Check the fulfillment status of line items

You can only submit a cancellation request for an order if all of the line items in the order haven't shipped. To determine the status of the line items in the order, use the order query before you attempt to cancel the order. For details, see Get line item IDs and package information details. In the state field of the PackageInformationDetails, if all line items are PENDING, then you can submit a cancellation request. Otherwise, the cancelOrder mutation returns 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 shopper made a mistake when placing the order.
  • ITEMS_ARRIVING_LATE: The shopper canceled the order because some items wouldn’t arrive on time.
  • INCORRECT_SHIPPING_ADDRESS: The shopper used an incorrect shipping address when placing the order.
  • OUT_OF_STOCK: The item went out of stock after the order was placed.
  • PAYMENT_ISSUE: There was an issue charging a shopper for the purchase.
  • OTHER: The reason for cancellation doesn't match an available value. You can enter a reason in the note field.

For the definitions of cancellation reasons, see CancellationDetails.

After you call cancelOrder, the cancellation state of the order changes to PENDING while determining whether the order can be canceled. One of two things happens based on the result:

  • Success: If the order can be canceled, the cancellation state is set to SUCCESS, and a REFUND_REQUESTED event occurs. For details about how to handle the event, see Steps to Process Refunds.
  • Failure: If the order can't be canceled, for example if the order has already been shipped, the cancellation state is set to REJECTED, and the call to cancelOrder returns an error.

For details about cancellation states, see CancellationDetails.

Request order cancellation

This example shows how to request order cancellation.

Request
// GraphQL mutation
mutation cancelOrder{
    cancelOrder(
        orderIdentifier: { 
          orderId: "example-order-id" 
        }
        input: {
            aliases: [{
                aliasType: "EXT_CANCEL_ID"
                aliasId: "example-external-cancellation-id"
              }
            ]
            reason: "ORDERED_BY_MISTAKE"
            additionalComments: "Order placed by mistake"
    }
    ) {
    cancellation {
       id
       aliases {
         aliasType
         aliasId
       }
       state
       reason
       additionalComments
       createdAt
       updatedAt
       canceledFor {
         orderLineItems {
           lineItem {
             id
           }
           amount {
             value
             unit
           }
         }
       }
     }
   }
 }
Response
{
    "data": {
        "cancelOrder": {
            "cancellation": {
                "id": "example-cancellation-id",
                "state": "PENDING",
                "aliases": [
                   {
                      "aliasId": "example-external-cancellation-id",
                      "aliasType": "EXT_CANCEL_ID"
                   }
                ],
                "reason": "ORDERED_BY_MISTAKE",
                "additionalComments": "Order placed by mistake",
                "createdAt": "2024-07-19T06:47:22.138Z",
                "updatedAt": "2024-07-19T06:47:22.138Z",
                "requestedBy": "MERCHANT",
                "canceledFor": {
                    "orderLineItems": [
                      {
                           "lineItem": {
                              "id": "example-line-item-id"
                           },
                           "amount": {
                              "value": 1,
                              "unit": "ONE"
                           }
                       }
                    ]
                }
            }
        }
    }
}

Request order cancellation with only an order identifier

This example shows how to request cancellation with only an order identifier.

Request
// GraphQL mutation
mutation cancelOrder{
    cancelOrder(
        orderIdentifier: { 
          orderId: "example-order-id" 
        }
    ) {
    cancellation {
       id
       aliases {
         aliasType
         aliasId
       }
       state
       reason
       additionalComments
       createdAt
       updatedAt
       canceledFor {
         orderLineItems {
           lineItem {
             id
           }
           amount {
             value
             unit
           }
         }
       }
     }
   }
 }
Response
{
    "data": {
        "cancelOrder": {
            "cancellation": {
                "id": "example-cancellation-id",
                "state": "PENDING",
                "aliases": [],
                "reason": null,
                "additionalComments": null,
                "createdAt": "2024-07-05T18:15:53.662Z",
                "updatedAt": "2024-07-05T18:15:53.662Z",
                "requestedBy": "MERCHANT",
                "canceledFor": {
                    "orderLineItems": [
                       {
                          "lineItem": {
                             "id": "example-line-item-id"
                          },
                          "amount": {
                              "value": 1,
                              "unit": "ONE"
                           }
                       }
                    ]
                }
            }
        }
    }
}

Request order cancellation when your reason isn't in the reason list

This example shows how to request order cancellation and provide a cancellation reason that's not in the cancellation reason list. In this case, choose OTHER as the reason and add your reason in the note field.

Request
// GraphQL mutation
mutation cancelOrder{
    cancelOrder(
        orderIdentifier: { 
          orderId: "example-order-id" 
        }
        input: {
            aliases: [{
               aliasType: "EXT_CANCEL_ID"
               aliasId: "example-external-cancellation-id"
              }
            ]
            reason: "OTHER"
            note: "DAMAGED PRODUCT"
    }
    ) {
    cancellation {
       id
       aliases {
         aliasType
         aliasId
       }
       state
       reason
       additionalComments
       createdAt
       updatedAt
       canceledFor {
         orderLineItems {
           lineItem {
             id
           }
           amount {
             value
             unit
           }
         }
       }
     }
   }
 }
Response
{
    "data": {
        "cancelOrder": {
            "cancellation": {
                "id": "example-cancellation-id",
                "state": "PENDING",
                "aliases": [
                  {
                     "aliasId": "cancel-ext-1",
                     "aliasType": "external-cancellation-id"
                  }
                ],
                "reason": "OTHER",
                "additionalComments": "DAMAGED PRODUCT",
                "createdAt": "2024-07-19T06:47:22.138Z",
                "updatedAt": "2024-07-19T06:47:22.138Z",
                "requestedBy": "MERCHANT",
                "canceledFor": {
                    "orderLineItems": [
                        {
                            "lineItem": {
                                "id": "example-line-item-id"
                            },
                            "amount": {
                                "value": 1,
                                "unit": "ONE"
                            }
                        }
                    ]
                }
            }
        }
    }
}

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