Tutorial: Cancel a Shipment
How to cancel a previously created shipment.
API Version: v2
This tutorial shows how to cancel a previously created shipment. The cancelShipment
operation cancels a shipment that has not been picked up for delivery (EU, NA and IN) and cancels a shipment that has been picked up and in transit (IN only).
Note: Carrier cancellation windows vary. Please refer to Seller Central help for carrier-specific cancellation/refund windows.
Note: The cancelShipment
operation is not available for Direct Fulfillment shipments.
Prerequisites
To complete this tutorial, you will need:
- Enrollment in an eligible program.
- A selling-partner account if you are an Amazon seller or are working with an Amazon seller to create and manage shipments.
- Authorization from the selling-partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
Request example
To cancel a shipment, send a POST
request to the /v2/shipments/{shipmentId}/cancel
endpoint.
Sample API Request
PUT https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/amzn1.sid.87906797587784.100/cancel
x-amzn-shipping-business-id: [x-amzn-shipping-business-id](https://developer-docs.amazon.com/amazon-shipping/docs/frequently-asked-questions#which-x-amzn-shipping-business-id-to-use-as-request-header-while-calling-shipping-v2-api)
x-amz-access-token: Atza|IwEBIGorlXXX
API Response example
{
"payload": {}
}
Cancel an In-Transit Shipment (IN Market)
For the IN market, you can now cancel shipments that are in-transit, subject to certain conditions.
Eligibility
Cancellation is allowed for shipments in READY_FOR_RECEIVE and IN_TRANSIT status.
Cancellation is allowed for shipments in transit. Cancellation is NOT allowed for shipments that are Picked but not arrived at pick up node, Out for delivery, Delivered, Returned to origin, Lost, Missing.
Request example
The request format remains the same for in-transit cancellations:
Sample API Request
PUT https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/amzn1.sid.87906797587784.100/cancel
x-amzn-shipping-business-id: [x-amzn-shipping-business-id](https://developer-docs.amazon.com/amazon-shipping/docs/frequently-asked-questions#which-x-amzn-shipping-business-id-to-use-as-request-header-while-calling-shipping-v2-api)
x-amz-access-token: Atza|IwEBIGorlXXX
Response example
A successful in-transit cancellation request returns the HTTP 200 OK status code and the following JSON response body:
{
"payload": {}
}
Error Response
If the cancellation is not possible, you may receive the following error response:
Shipment not eligible for cancellation:
{
"errors": [
{
"code": "InvalidInput",
"message": "Invalid input.",
"details": "Cancellation failed as shipment is in ineligible state."
}
]
}
Best practices
- Always check the shipment status before attempting to cancel.
- For bulk cancellations, limit the number of shipments in a single request to improve response times.
- Handle potential error responses gracefully in your application.
Updated 6 days ago