API reference
Retrieve a delivery
One delivery, by id or tracking code — both work, because an integrator usually stores whichever their own system saw first.
GET
/api/v1/dispatch/deliveries/{id}Path parameter#
idstringrequiredEither the delivery
id (a UUID) or its tracking_code (e.g. DCAB12CD34). Tracking codes are matched case-sensitively, as returned.Scoped to your key
The lookup is scoped to your company and your key's environment. A test key asking for a live delivery gets
404, not a redacted record — a sandbox must never be able to surface a real customer's address.Request#
curl "https://api.rheochat.com/api/v1/dispatch/deliveries/DCAB12CD34" \
-H "Authorization: Bearer rk_test_YOUR_KEY"Response#
200
{
"id": "0f9a1c8e-6b2a-4f0d-9b7e-3c5a1d2e4f60",
"tracking_code": "DCAB12CD34",
"environment": "live",
"livemode": true,
"status": "in_transit",
"payment_status": "paid",
"reference": "your-order-4821",
"currency": "NGN",
"delivery_fee": 1800,
"platform_fee": 200,
"rider_payout": 1400,
"distance_km": 4.62,
"eta_minutes": 26,
"pickup": {
"name": "Mama Put Kitchen",
"phone": "+2348012345678",
"address": "12 Ahmadu Bello Way, Jos",
"lat": 9.8965,
"lng": 8.8583
},
"dropoff": {
"name": "Amaka O.",
"phone": "+2348098765432",
"address": "5 Rwang Pam St, Jos",
"lat": 9.9285,
"lng": 8.8921
},
"item_description": "Jollof rice x2",
"created_at": "2026-09-20T09:14:02.118Z",
"events": [
{ "status": "pending", "note": "Booking created via API", "created_at": "2026-09-20T09:14:02.118Z" },
{ "status": "assigned", "note": "Assigned to Musa I.", "created_at": "2026-09-20T09:14:47.902Z" },
{ "status": "picked_up", "note": "Parcel collected", "created_at": "2026-09-20T09:31:08.310Z" },
{ "status": "in_transit", "note": "On the way to the drop-off", "created_at": "2026-09-20T09:31:44.007Z" }
],
"request_id": "b6d3f7c2-…"
}Fields
| Field | Type | Meaning |
|---|---|---|
status | string | Where the parcel is. See the lifecycle. |
payment_status | string | Where the money is: cod, unpaid, paid, failed, refunded. |
reference | string | null | Your own identifier, as sent at booking. |
pickup | object | Name, phone, address and coordinates of the collection point. |
dropoff | object | The same for the destination. |
item_description | string | null | What is being carried. |
created_at | string | ISO 8601, UTC. |
events | array | Every status change, oldest first, each with a human note and a timestamp. |
Rider identity and live position are not returned by this endpoint. The public tracking page for a tracking_code shows them to the recipient, which is the person that information is for.
Errors#
| Status | Code | When |
|---|---|---|
| 401 | invalid_api_key | Bad or revoked key. |
| 404 | not_found | No delivery with that id or tracking code — in this environment, for this company. Check your key's environment before assuming it is gone. |
Polling#
There are no webhooks yet, so this endpoint is how you follow a delivery. Poll roughly every 30 seconds while a delivery is in flight, every 60 while it waits for a rider, and stop once it reaches delivered or cancelled. See Following a delivery.