Skip to main content

Quotes and jobs

How a price is made​

IDM prices every delivery on its own servers, from data Intellisol administers. You send two pins, a vehicle type and a service type. IDM then:

  1. Resolves both pins to a suburb, zone and gateway under the boundaries in force. A pin outside the service area is LOCATION_NOT_SUPPORTED; one IDM cannot place with confidence is LOCATION_NOT_CONFIRMED.
  2. Classifies the trip: within one zone (INTRA_ZONE), between zones of one gateway (INTER_ZONE), or between gateways (INTER_GATEWAY).
  3. Checks the vehicle is offered for this delivery. If not: VEHICLE_UNAVAILABLE.
  4. Measures the verified road distance with an approved routing provider. Straight-line distance, your own estimate or a rider's mileage never set a price.
  5. Applies the active pricing version: a base fare, an included distance, one per-kilometre rate for the classification, and the multipliers in force. It rounds once, at the end, to two decimal places.

The answer gives you the fee and the pricing_version that produced it. What the customer pays is fixed in a pricing snapshot the moment the quote is confirmed. A later change to prices never changes a confirmed delivery. See Delivery cost for the customer-facing explanation.

Money is a string

delivery_fee is always a string with two decimals, such as "38.50", with currency beside it (GHS). Parse it as a decimal, never a floating-point number.

Whether you also get a breakdown depends on whether Intellisol has given your tenant detailed pricing visibility.

Service types​

service_typeUse it for
EXPRESSThe fastest pickup and delivery
PRIORITYFaster than standard
STANDARDEveryday deliveries; may share a route with others going the same way
NEXT_DAYNot urgent; may share a route

The time promise for each service type is configured by Intellisol. STANDARD and NEXT_DAY deliveries may be carried on a shared route. Each one keeps its own price, receipt and tracking.

Quote expiry​

A quote has an expires_at time on IDM's clock. Confirm it before then, or ask for a new one. After it, confirming is refused with QUOTE_EXPIRED. The same code with detail.reason: geography_changed means a pin now falls in a different area because the boundaries changed; quote again.

Confirming: one quote, one job​

POST /v1/delivery/jobs with the quote_reference turns the quote into a delivery job with a DX-… reference. In one step IDM re-checks the quote, the places and the vehicle, freezes the price, writes the job and releases it to dispatch (status DELIVERY_REQUESTED).

  • You never send the fee again. The quote reference is the contract.
  • Confirming the same quote again, with any key, returns the same job.
  • You may name a preferred_partner (from GET /v1/partners). If it cannot take the job you get NO_ELIGIBLE_PARTNER, or PARTNER_BLOCKED if it is blocked for unpaid fees.
  • Outside your tenant's availability windows the request is VALIDATION_FAILED with detail.reason: outside_availability_window.

The 201 answer carries tracking_links.sender_url and tracking_links.recipient_url. Send them to your customer and their recipient through your own channel. They are shown only on that answer (and its idempotent replay) because IDM keeps only a hash of each link. Store them if you need to send them again.

The job's two statuses​

Every job answer has both:

  • status: the internal lifecycle, for your systems. See Delivery states.
  • customer_status: the words to show a person, such as Delivery partner assigned or In a shared delivery queue — position 2. See Tracking statuses.

Show customer_status to customers. Do not invent your own wording from status, because some internal steps (offers, relays between riders) are deliberately not shown to customers.

Payment is separate​

Delivery status and payment status are different things in IDM. A delivered parcel can still be unpaid, and a paid delivery can still be on its way. Never infer one from the other.