Dispatch & Zones

When you create an order, IDeliver automatically calculates the delivery fare and assigns the nearest available rider. This page explains how that works.

How dispatch works

1. Zone resolution — The pickup address is matched to a pricing zone (e.g. Lagos Island, Mainland, Abuja).
2. Fare calculation — The fare is calculated using the zone’s rate card: base fare + per-kilometre rate + any active time multiplier.
3. Rider assignment — The nearest available rider within your merchant dispatch radius is offered the job.
4. Real-time updates — Status events are sent to your webhook as the rider moves.

Delivery fare formula

Fare = (Base Fare + (Distance km − Base Distance km) × Per-km Rate) × Time Multiplier

All amounts are in Nigerian Naira (NGN). Your wallet is charged when a rider picks up the order.

Checking the current fare for an address

You can get a real-time fare estimate before creating an order using the Telegram bot command /quote, or by calling the fare preview endpoint:

GET /v1/public/pricing/rate-card-preview?lat=6.4550&lng=3.3940&vehicle_type=motorcycle

This returns the active rate card and any time multipliers for that location.

Coverage & error codes (preflight)

• Public pricing preview may return outside_coverage when the coordinates are outside platform pricing coverage.
• Internal fare estimation paths may surface pickup_outside_coverage when pickup is outside merchant dispatch / pricing zones.
• POST /v1/orders now validates coordinates against your merchant dispatch zones and rejects out-of-bounds orders with 400 OUT_OF_COVERAGE_AREA. Use GET /v1/coverage/check as a pre-flight check before creating orders. See Errors & Rate Limits.
• Dispatch zone GeoJSON for your tenant is available at GET /v1/me/dispatch/zones with a merchant access JWT (orders:read). ilv_… API keys alone cannot call /v1/me/* — either mint a JWT (POST /v1/auth/token) from your backend or export zones from the dashboard. See Integrator readiness.

Surge pricing

Surge pricing (time multipliers) activates automatically during high-demand periods such as:

• Morning rush (7–9am)
• Evening rush (5–7pm)
• Weekends and public holidays
• Manual operator overrides during events or bad weather

When surge is active, the multiplier is shown in the fare breakdown and on the public tracking page.

Merchant dispatch zones

As a merchant, you can configure a custom dispatch zone in your dashboard to restrict which riders are offered your deliveries. This is useful for:

• Ensuring only riders familiar with your area receive jobs
• Setting preferred maximum delivery distances
• Scheduling specific dispatch windows (e.g. lunch-only deliveries)

To manage your zones, go to Settings → Dispatch Zones in the merchant dashboard.

Vehicle types

Automatic vehicle suggestion

When you include weight_kg (and optionally length_cm, width_cm, height_cm, is_fragile) in your order’s standardized fields but omit vehicle_type_hint, the API automatically selects the best vehicle:

You can override this by explicitly setting vehicle_type_hint in your order payload. See API Reference — Parcel Dimensions.

Next steps

• Webhooks & Events — Track every status change in real-time
• API Playground — Test fare estimates interactively