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

Query parameters#

pickup_latnumberrequired
Latitude of the collection point, decimal degrees.
pickup_lngnumberrequired
Longitude of the collection point.
dropoff_latnumberrequired
Latitude of the destination.
dropoff_lngnumberrequired
Longitude of the destination.
weight_kgnumberoptional
Parcel weight. Defaults to 0. Affects both the price and which vehicle classes can carry it. Must not be negative.
vehicle_idstringoptional
Price 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

FieldTypeMeaning
delivery_feenumberWhat the customer pays for the delivery. Company price plus platform fee.
company_pricenumberYour company's share before the platform fee is added on top.
platform_feenumberRheoChat's fee, already included in delivery_fee.
rider_payoutnumberWhat the rider earns for this trip.
distance_kmnumberRoad-equivalent distance, not straight-line.
eta_minutesnumberEstimated door-to-door minutes; traffic-aware where live traffic data is available.
vehicle_idstring | nullThe vehicle class this quote was priced with. Null when priced on company defaults.
fee_breakdownobjectWhat an online charge would look like — see the gross-up. total is what the customer is charged if they pay online.
breakdownobjectHow the price was built: distance band, fuel surcharge, weight cost, rider payout.
vehiclesarrayEvery active vehicle class, priced. Capable ones first, cheapest first.

The vehicles array

FieldMeaning
vehicle_idPass this back as vehicle_id to price or book that class.
vehicle_nameDisplay name — "Motorcycle", "Car".
iconAn icon hint for your own UI.
max_weight_kgCapacity of the class.
capableWhether 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_feeWhat the customer would pay with this class.
eta_minutesEstimate for this class.

Errors#

StatusCodeWhen
400invalid_requestA coordinate is missing or not a number, or weight_kg is negative. details.missing names the fields.
403company_inactiveBookings are switched off for the company, or the company is not approved.
422unprocessableA 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.