Skip to main content
A shipment can be cancelled until a driver is assigned to it. After that, cancellation is refused — a driver is already on the way, and the shipment has to be resolved in the field.
Requires shipments:write. The body is optional; the response is the shipment, now CANCELLED.

​
The reason

Send one if you have something more specific to record:
reason is an uppercase machine code matching ^[A-Z][A-Z0-9_]{1,47}$ — a stable value both systems can reason about, not free text for a human to read. It defaults to MERCHANT_REQUESTED.

​
When it is refused

The shipment has been assigned, picked up, delivered, failed, or already cancelled. Read the shipment back to see where it actually is.
reason did not match the pattern. The violations array names the offending field.
The shipment does not exist, or it belongs to another merchant.
Cancellation racing an assignment is normal, not exceptional. Handle 409 by re-reading the shipment and reporting its real status — not by retrying the cancel.

​
Retrying safely

Cancellation is idempotent on the shipment id, so an uncertain retry replays the original outcome rather than attempting a second cancellation. You do not need to send an Idempotency-Key; see Idempotency and ETags if you want to supply your own.