🗑️ Cancel a (draft) shipment

This endpoint lets you cancel a shipment that you created with the create shipment endpoint. You can cancel a draft shipment or a booked shipment.

Draft shipment: we cancel the shipment in your ParcelParcel account. The shipment was not sent to the carrier, so the carrier does not need to do anything.
Booked shipment: we send the cancellation to the carrier. This works only while the carrier has not yet picked up or scanned the parcel. After the parcel is in transit, you can no longer cancel the shipment.

You can only cancel shipments that belong to your own account.

Method

To cancel a shipment, use the following method:

POST

Endpoint

Use the following endpoint:

https://services.parcelparcel.com/partners-api/v1/shipments/{shipmentId}/cancel

Replace {shipmentId} with the id that you got in the response when you created the shipment.

Header

Add the following headers:

Name	Value
Content-Type	application/json
X-PP-API	`{YourAPIKey}@{YourAPISecret}`

Don't have an API Key and API Secret yet? Check our Authentication page to see how to get them in under a minute.

Body

This endpoint does not need a request body.

Response

The response body is a JSON object with the following elements:

Name	Value	Comments
cancelled	(bool)	`true` if the shipment is cancelled. `false` if we could not cancel the shipment.
message	(string)	Tells you the result. If the carrier refuses the cancellation, this contains the carrier's reason.

Status codes

Status code	Meaning
200 OK	The shipment is cancelled, or it was already cancelled before. `cancelled` is `true`.
409 Conflict	We could not cancel the shipment. The parcel is already in transit, or the carrier refused the cancellation. `cancelled` is `false`. Read `message` for the reason.
404 Not Found	We could not find the shipment in your account. Make sure that the `shipmentId` is correct.

Examples

Below are some examples to get you up and running fast. Don't know how to test these requests? Check our guide.

Request example - Cancel a shipment

curl --location --request POST 'https://services.parcelparcel.com/partners-api/v1/shipments/1588448/cancel' \
--header 'X-PP-API: `{YourAPIKey}@{YourAPISecret}`' \
--header 'Content-Type: application/json'

POST /partners-api/v1/shipments/1588448/cancel HTTP/1.1
Host: services.parcelparcel.com
X-PP-API: `{YourAPIKey}@{YourAPISecret}`
Content-Type: application/json

Don't forget to change the X-PP-API element in the header, or this request will not work. Don't know where to get your API Key and API Secret? Check our Authentication page to see how to get them in under a minute.

Response example - Shipment cancelled (200)

{
    "cancelled": true,
    "message": "Shipment was cancelled"
}

Response example - Shipment already cancelled (200)

{
    "cancelled": true,
    "message": "Shipment was already cancelled"
}

Response example - Shipment already in transit (409)

{
    "cancelled": false,
    "message": "Shipment is already in transit and can no longer be cancelled"
}

Response example - Shipment not found (404)

"Shipment not found"