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/deliveries

Headers#

Authorizationstringrequired
Your key: Bearer rk_live_…
Content-Typestringrequired
application/json
Idempotency-Keystringoptional
Makes 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_namestringrequired
Who the rider is collecting from. Shown in the rider app.
pickup_phonestringrequired
Reachable number at the collection point. The rider will call it.
pickup_addressstringrequired
Human-readable address, for the rider to read and navigate by.
pickup_latnumberrequired
Latitude. Must be inside Nigeria.
pickup_lngnumberrequired
Longitude.
pickup_emailstringoptional
Optional. Receives booking notifications for the collection side.

Drop-off

dropoff_namestringrequired
The recipient.
dropoff_phonestringrequired
The recipient's number. Also used to derive a contact record when no email is given.
dropoff_addressstringrequired
Where the rider is going.
dropoff_latnumberrequired
Latitude. Must be inside Nigeria.
dropoff_lngnumberrequired
Longitude.
dropoff_emailstringoptional
Optional, 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_descriptionstringoptional
What is being carried. The rider sees this — "Jollof rice x2" is useful, "Order" is not.
weight_kgnumberoptional
Parcel weight. Affects price and which vehicles can take the job.
vehicle_idstringoptional
Book a specific vehicle class, from the vehicles array of a quote. Omit to let the company's rules choose.
payment_method"cod" | "online"optional
Defaults to online. cod requires cash on delivery to be enabled for the company; live online requires a connected payout account. See Payments.
referencestringoptional
Your 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.

FieldLimit
Names — pickup_name, dropoff_name120 characters
Addresses300 characters
item_description500 characters
reference120 characters
Emails254 characters, and must look like an address
Phones32 characters, digits and + ( ) - . and spaces, at least 7 digits
weight_kga 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-…"
}
FieldMeaning
idOur identifier. Stable, and what we will ask for in support.
tracking_codeShort human-friendly code, e.g. DCAB12CD34. Works anywhere an id does, and is what the recipient sees.
statusAlways pending on creation.
referenceYour identifier, echoed back.
delivery_feeWhat the customer pays. Platform fee included.
platform_feeRheoChat's cut, already inside delivery_fee.
rider_payoutWhat the rider earns.
eta_minutesEstimated door-to-door time at booking.
company_nameYour company, for receipts and customer-facing copy.
paymentHow to collect. See Payments.
livemodefalse for a test booking. Log it.

The payment object

MethodShape
cod{ "method": "cod" } — nothing to do. The rider collects cash.
onlineCarries 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 modeAdds test: true and omits tx_ref — there is nothing to charge.

Errors#

StatusCodeWhen
400invalid_requestBody 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.
402quota_exceededThis month's API booking allowance (10,000 on Pro) is spent. Details.
402plan_requiredA live key, and the company is not on the Dispatch Pro plan. Test keys are free.
403company_inactiveThe company is unapproved, suspended, or has bookings switched off.
409idempotency_conflictThat Idempotency-Key was already used for a different booking.
422unprocessableCoordinates outside Nigeria; COD requested but not enabled; live online booking with no payout account connected.
500internal_errorOur fault. Retry with the same idempotency key.

What happens after a 201#

  • A pending event 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 stays pending indefinitely.
  • Test mode: the row and the timeline event are written, and that is all — no rider, no settlement, no email.