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 aREFUND_REQUESTEDevent 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 tocancelOrderreturns 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:
- Call the Buy with Prime API: Call the
orderquery and examine the cancellation details for the line items in the order. For examples, see Order Cancellation. - Monitor events: Subscribe to the Buy with Prime events in the Prerequisites to receive a
PACKAGE_DELIVERY_CANCELLEDevent when one or more items are successfully canceled. Buy with Prime also initiates a refund request and sends aREFUND_REQUESTEDevent to you for processing. For details about refunds, see Steps to Process Refunds.
Step 4: Update your order management system
Finally, update your order management system and downstream systems to reflect the cancellation details.
Related topics
Updated 2 months ago