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}/cancel

Parameters#

Path
idstringrequired
The delivery id or its tracking_code. Both work.
Body (optional)
reasonstringoptional
Why. 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 statusResult
pending, scheduled, assigned, acceptedCancelled. 200.
cancelledAlready cancelled — still 200. A retried cancel never fails because the first one worked.
picked_up, in_transit, delivered422 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#

StatusCodeWhen
401invalid_api_keyBad or revoked key.
404not_foundNo such delivery in this environment.
422unprocessableThe 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": "…"
}