API reference
Quote a delivery
What a delivery would cost, before committing to it. Priced by the same function that prices the booking page, so a quote is never a different arithmetic from a booking.
GET
/api/v1/dispatch/quoteQuery parameters#
pickup_latnumberrequiredLatitude of the collection point, decimal degrees.
pickup_lngnumberrequiredLongitude of the collection point.
dropoff_latnumberrequiredLatitude of the destination.
dropoff_lngnumberrequiredLongitude of the destination.
weight_kgnumberoptionalParcel weight. Defaults to
0. Affects both the price and which vehicle classes can carry it. Must not be negative.vehicle_idstringoptionalPrice one specific vehicle class. Omit to let the company's own selection rules choose — the
vehicles array in the response lists every option either way.Coordinates, not addresses
Pricing is by coordinate. Geocode on your side, and keep the human-readable address for the booking, where the rider actually reads it. Both points must fall inside Nigeria or the call is refused with
422 unprocessable.Request#
curl -G "https://api.rheochat.com/api/v1/dispatch/quote" \
-H "Authorization: Bearer rk_test_YOUR_KEY" \
--data-urlencode "pickup_lat=9.8965" \
--data-urlencode "pickup_lng=8.8583" \
--data-urlencode "dropoff_lat=9.9285" \
--data-urlencode "dropoff_lng=8.8921" \
--data-urlencode "weight_kg=2"Response#
200
{
"environment": "test",
"currency": "NGN",
"delivery_fee": 1800,
"company_price": 1600,
"platform_fee": 200,
"rider_payout": 1400,
"distance_km": 4.62,
"eta_minutes": 26,
"vehicle_id": "9f1c…",
"fee_breakdown": {
"delivery_fee": 1800,
"transaction_fee": 37,
"vat": 3,
"stamp_duty": 0,
"total": 1840
},
"breakdown": {
"distance_km": 4.62,
"zone": { "zone_id": "local", "name": "Local (≤ 10 km)", "flat_premium": 0, "multiplier": 1 },
"rider_distance_cost": 1150,
"fuel_surcharge_pct": 0,
"fuel_surcharge_amount": 0,
"weight_cost": 250,
"total_rider_cost_raw": 1400,
"total_customer_fee": 1600,
"rider_payout": 1400,
"admin_net_profit": 200
},
"vehicles": [
{
"vehicle_id": "9f1c…", "vehicle_name": "Motorcycle", "icon": "bike",
"max_weight_kg": 20, "capable": true,
"delivery_fee": 1800, "company_price": 1600, "eta_minutes": 26
},
{
"vehicle_id": "2b7e…", "vehicle_name": "Car", "icon": "car",
"max_weight_kg": 80, "capable": true,
"delivery_fee": 2650, "company_price": 2400, "eta_minutes": 22
}
],
"request_id": "b6d3f7c2-…"
}Fields
| Field | Type | Meaning |
|---|---|---|
delivery_fee | number | What the customer pays for the delivery. Company price plus platform fee. |
company_price | number | Your company's share before the platform fee is added on top. |
platform_fee | number | RheoChat's fee, already included in delivery_fee. |
rider_payout | number | What the rider earns for this trip. |
distance_km | number | Road-equivalent distance, not straight-line. |
eta_minutes | number | Estimated door-to-door minutes; traffic-aware where live traffic data is available. |
vehicle_id | string | null | The vehicle class this quote was priced with. Null when priced on company defaults. |
fee_breakdown | object | What an online charge would look like — see the gross-up. total is what the customer is charged if they pay online. |
breakdown | object | How the price was built: distance band, fuel surcharge, weight cost, rider payout. |
vehicles | array | Every active vehicle class, priced. Capable ones first, cheapest first. |
The vehicles array
| Field | Meaning |
|---|---|
vehicle_id | Pass this back as vehicle_id to price or book that class. |
vehicle_name | Display name — "Motorcycle", "Car". |
icon | An icon hint for your own UI. |
max_weight_kg | Capacity of the class. |
capable | Whether it can carry the weight_kg you asked about. Incapable classes are still listed, so you can explain why the cheap option is unavailable. |
delivery_fee | What the customer would pay with this class. |
eta_minutes | Estimate for this class. |
Errors#
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A coordinate is missing or not a number, or weight_kg is negative. details.missing names the fields. |
| 403 | company_inactive | Bookings are switched off for the company, or the company is not approved. |
| 422 | unprocessable | A coordinate falls outside Nigeria. |
Notes#
A quote is advisory and carries no reservation. Booking re-prices server-side and ignores any amount you send, so a stale or doctored quote cannot become a cheap delivery — and a quote taken an hour ago can legitimately differ from what the booking charges if a promo expired or surge pricing moved in between. Quote close to the moment you book.