Cancel a shipment

POST /shipments/{shipment_id}/cancel

Cancels a shipment that the carrier has not yet collected.

Path parameters

Parameter	Type		Description
`shipment_id`	string	required	Unique identifier of the shipment.

Example request

curl -X POST "https://api.parcelly.dev/v1/shipments/shp_7Hk2mQ9x/cancel" \
  -H "Authorization: Bearer $PARCELLY_API_KEY"

Responses

200 The shipment was cancelled.

Field	Type		Description
`id`	string	required	Unique identifier of the shipment.
`status`	string	required	Current state of the shipment. One of: `label_created`, `in_transit`, `out_for_delivery`, `delivered`, `cancelled`.
`tracking_number`	string	required	Carrier tracking number.
`carrier`	string	required	ID of the carrier handling the shipment.
`price`	number	required	Shipping price in USD.
`created_at`	string (date-time)	required	When the shipment was created.
`estimated_delivery`	string (date)	optional	Estimated delivery date, once known.

Example response

{
  "id": "shp_7Hk2mQ9x",
  "status": "in_transit",
  "tracking_number": "PCL1234567890",
  "carrier": "swiftpost",
  "price": 12.5,
  "created_at": "2026-01-20T09:30:00Z",
  "estimated_delivery": "2026-01-23"
}

409 The shipment can no longer be cancelled.

Field	Type		Description
`code`	string	required	Machine-readable error code.
`message`	string	required	Human-readable explanation of the error.

Example response

{
  "code": "shipment_not_found",
  "message": "No shipment exists with this ID."
}