Tutorial: Cancel a 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.