API reference
Cancel a delivery
Calls off a delivery that has not been collected yet. Once a rider physically holds the parcel, cancelling is an operations conversation, not an API call.
POST
/api/v1/dispatch/deliveries/{id}/cancelParameters#
Path
idstringrequiredThe delivery
id or its tracking_code. Both work.Body (optional)
reasonstringoptionalWhy. Written into the delivery's timeline as
Cancelled via API: …, where the dispatch team and the customer will read it. An empty or absent reason is fine; a vague one helps nobody.When cancellation is allowed#
| Current status | Result |
|---|---|
pending, scheduled, assigned, accepted | Cancelled. 200. |
cancelled | Already cancelled — still 200. A retried cancel never fails because the first one worked. |
picked_up, in_transit, delivered | 422 unprocessable, with the blocking status in details.status. |
Idempotent by nature
Because cancelling something already cancelled succeeds, this endpoint needs no
Idempotency-Key — retry it as often as you like. See Idempotency.Request#
curl -X POST "https://api.rheochat.com/api/v1/dispatch/deliveries/DCAB12CD34/cancel" \
-H "Authorization: Bearer rk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "reason": "Customer cancelled the order" }'Response#
200
{
"id": "0f9a1c8e-…",
"tracking_code": "DCAB12CD34",
"status": "cancelled",
"environment": "live",
"livemode": true,
"reason": "Customer cancelled the order",
"request_id": "b6d3f7c2-…"
}What cancelling does#
The delivery moves to cancelled, a timeline event records it with your reason, any assigned rider is released to take other work, and any unsettled ledger entry for the delivery is reversed. A payment already taken is not automatically refunded — refunds are handled by the dispatch company, because whether one is due is a commercial question rather than a technical one.
Errors#
| Status | Code | When |
|---|---|---|
| 401 | invalid_api_key | Bad or revoked key. |
| 404 | not_found | No such delivery in this environment. |
| 422 | unprocessable | The parcel is already with a rider, or the delivery is finished. |
422
{
"error": {
"code": "unprocessable",
"message": "A delivery that is 'picked_up' can no longer be cancelled through the API. Contact the dispatch company.",
"details": { "status": "picked_up" }
},
"request_id": "…"
}