API reference
Book a delivery
Creates a real delivery in your company's queue. The one endpoint that spends money and somebody's afternoon — and therefore the one to send an Idempotency-Key with.
POST
/api/v1/dispatch/deliveriesHeaders#
AuthorizationstringrequiredYour key:
Bearer rk_live_…Content-Typestringrequiredapplication/jsonIdempotency-KeystringoptionalMakes this call safe to retry. A repeat with the same key returns the original delivery and
Idempotent-Replay: true instead of creating a second one. 1–255 printable ASCII characters. Strongly recommended on every live booking — full detail here.Body#
Pickup
pickup_namestringrequiredWho the rider is collecting from. Shown in the rider app.
pickup_phonestringrequiredReachable number at the collection point. The rider will call it.
pickup_addressstringrequiredHuman-readable address, for the rider to read and navigate by.
pickup_latnumberrequiredLatitude. Must be inside Nigeria.
pickup_lngnumberrequiredLongitude.
pickup_emailstringoptionalOptional. Receives booking notifications for the collection side.
Drop-off
dropoff_namestringrequiredThe recipient.
dropoff_phonestringrequiredThe recipient's number. Also used to derive a contact record when no email is given.
dropoff_addressstringrequiredWhere the rider is going.
dropoff_latnumberrequiredLatitude. Must be inside Nigeria.
dropoff_lngnumberrequiredLongitude.
dropoff_emailstringoptionalOptional, and worth sending: it is how the recipient receives tracking updates and the delivery confirmation code. See Delivery confirmation.
The parcel and the payment
item_descriptionstringoptionalWhat is being carried. The rider sees this — "Jollof rice x2" is useful, "Order" is not.
weight_kgnumberoptionalParcel weight. Affects price and which vehicles can take the job.
vehicle_idstringoptionalBook a specific vehicle class, from the
vehicles array of a quote. Omit to let the company's rules choose.payment_method"cod" | "online"optionalDefaults to
online. cod requires cash on delivery to be enabled for the company; live online requires a connected payout account. See Payments.referencestringoptionalYour own identifier for this delivery — an order id, an invoice number. Stored and returned on every read, so your system and ours can be reconciled without a lookup table.
You cannot send a price
There is no amount field, and any you invent is ignored. Every booking is re-priced server-side by the same function behind the booking page, and the platform fee comes from that quote — so there is no API price list to drift, and no field to omit to book past the fee.
Field limits#
Over-long or malformed input is refused, not trimmed: half an address stored quietly is a delivery to half an address. The response names every field that failed, not just the first.
| Field | Limit |
|---|---|
Names — pickup_name, dropoff_name | 120 characters |
| Addresses | 300 characters |
item_description | 500 characters |
reference | 120 characters |
| Emails | 254 characters, and must look like an address |
| Phones | 32 characters, digits and + ( ) - . and spaces, at least 7 digits |
weight_kg | a number from 0 to 1000 |
400
{
"error": {
"code": "invalid_request",
"message": "weight_kg must not be negative",
"details": {
"problems": [
{ "field": "weight_kg", "message": "weight_kg must not be negative" },
{ "field": "dropoff_phone", "message": "dropoff_phone does not have enough digits to be a phone number" }
]
}
},
"request_id": "…"
}weight_kg is money
Weight is multiplied into the delivery fee, so it is checked strictly: a negative value would price as a discount, and a non-numeric one would poison the calculation. Send a number or leave it out.
Request#
curl -X POST "https://api.rheochat.com/api/v1/dispatch/deliveries" \
-H "Authorization: Bearer rk_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-4821" \
-d '{
"pickup_name": "Mama Put Kitchen",
"pickup_phone": "+2348012345678",
"pickup_address": "12 Ahmadu Bello Way, Jos",
"pickup_lat": 9.8965,
"pickup_lng": 8.8583,
"pickup_email": "[email protected]",
"dropoff_name": "Amaka O.",
"dropoff_phone": "+2348098765432",
"dropoff_address": "5 Rwang Pam St, Jos",
"dropoff_lat": 9.9285,
"dropoff_lng": 8.8921,
"dropoff_email": "[email protected]",
"item_description": "Jollof rice x2",
"weight_kg": 2,
"payment_method": "cod",
"reference": "your-order-4821"
}'Response#
201 Created. The delivery starts at pending and enters rider assignment — at once for cash on delivery, or on payment confirmation for an online booking.
201
{
"id": "0f9a1c8e-6b2a-4f0d-9b7e-3c5a1d2e4f60",
"tracking_code": "DCAB12CD34",
"environment": "test",
"livemode": false,
"status": "pending",
"reference": "your-order-4821",
"currency": "NGN",
"delivery_fee": 1800,
"platform_fee": 200,
"rider_payout": 1400,
"distance_km": 4.62,
"eta_minutes": 26,
"company_name": "Swift Wheels Logistics",
"payment": { "method": "cod", "test": true },
"request_id": "b6d3f7c2-…"
}| Field | Meaning |
|---|---|
id | Our identifier. Stable, and what we will ask for in support. |
tracking_code | Short human-friendly code, e.g. DCAB12CD34. Works anywhere an id does, and is what the recipient sees. |
status | Always pending on creation. |
reference | Your identifier, echoed back. |
delivery_fee | What the customer pays. Platform fee included. |
platform_fee | RheoChat's cut, already inside delivery_fee. |
rider_payout | What the rider earns. |
eta_minutes | Estimated door-to-door time at booking. |
company_name | Your company, for receipts and customer-facing copy. |
payment | How to collect. See Payments. |
livemode | false for a test booking. Log it. |
The payment object
| Method | Shape |
|---|---|
cod | { "method": "cod" } — nothing to do. The rider collects cash. |
online | Carries checkout_url — a hosted payment page to send the customer to — plus tx_ref, the grossed-up amount, a fee_breakdown and the subaccounts split, for charging it yourself instead. checkout_url is absent if Flutterwave was unreachable at booking; ask for one with /pay. |
| test mode | Adds test: true and omits tx_ref — there is nothing to charge. |
Errors#
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | Body is not JSON, a required field is missing (details.missing names them), a coordinate is not a number, or the Idempotency-Key is empty, too long, or not printable ASCII. |
| 402 | quota_exceeded | This month's API booking allowance (10,000 on Pro) is spent. Details. |
| 402 | plan_required | A live key, and the company is not on the Dispatch Pro plan. Test keys are free. |
| 403 | company_inactive | The company is unapproved, suspended, or has bookings switched off. |
| 409 | idempotency_conflict | That Idempotency-Key was already used for a different booking. |
| 422 | unprocessable | Coordinates outside Nigeria; COD requested but not enabled; live online booking with no payout account connected. |
| 500 | internal_error | Our fault. Retry with the same idempotency key. |
What happens after a 201#
- A
pendingevent is written to the delivery's timeline. - Cash on delivery: a settlement entry records the platform fee owed, a confirmation email goes out, and rider assignment begins immediately.
- Online: a hosted checkout page is created for the delivery and returned as
payment.checkout_url. Nothing is assigned until the payment is confirmed; an unpaid delivery stayspendingindefinitely. - Test mode: the row and the timeline event are written, and that is all — no rider, no settlement, no email.