Pricing a parcel
Quote before your customer pays, so the delivery fee you charge is the one you will be charged.
/v1/quotesRequires quotes:read. Creates nothing, so call it as often as you like. A quote is priced exactly as POST /v1/parcels will charge for the same fields.
Request
| Field | Required | Notes |
|---|---|---|
delivery_mode | yes | STATION to a pickup town, DOOR inside Nairobi. |
origin_lat, origin_lng | yes | Where a rider collects: your shop. |
dest_town_id | either | From /v1/towns. |
dest_lat, dest_lng | either | Use instead of a town for door delivery in Nairobi. |
category | no | STANDARD (default), FRAGILE, LARGE_ITEM or BULK. See below. |
package_size | no | S, M, ML, L, BULKY. For standard and fragile parcels. |
weight_kg | no | Billed at the larger of size and weight. |
length_cm, width_cm, height_cm | no | The box size. A light but bulky box is priced on its size, as it is measured at pickup. |
quantity | no | Identical pieces, or how many of a large item (1 to 5). |
large_item | for LARGE_ITEM | A key from GET /v1/catalog, such as fridge_single. |
bulk_lines | for BULK | Array of { unit, count, weight_kg? }. Units are in the catalog. |
declared_value | no | What the goods are worth, in KES. Drives cover. |
is_fragile | no | Older name for category: "FRAGILE". Still accepted. |
is_perishable | no | Food and other goods that spoil. Adds a handling charge. |
Supply either dest_town_id or both destination coordinates. Neither gives missing_destination.
Response
{
"object": "quote",
"currency": "KES",
"category": "LARGE_ITEM",
"requires_quote": false,
"quote_reason": null,
"delivery_fee": 2000,
"pickup_fee": 700,
"cover": 600,
"insurance": 600,
"total": 3300,
"package_size": "BULKY",
"pickup_mode": "DOOR_PICKUP",
"breakdown": [
"Single-door fridge 2000",
"Pickup in Nairobi (10.1 km) +700",
"Cover for KES 35,000 +600",
"Collect at destination pickup town"
]
}Charge total. The breakdown is there so you can explain a price to a customer who asks. insurance is the older name for cover and carries the same number.
Booking types
| Category | Send | How it is priced |
|---|---|---|
STANDARD | package_size, weight_kg | Zone and size rate card, plus a per-kg charge over the size allowance. |
FRAGILE | as standard, plus declared_value | Standard price plus 40% for handling, at least KES 150 a piece. |
LARGE_ITEM | large_item, quantity, declared_value | A flat price per item, the same to every town. Pickup towns only. |
BULK | bulk_lines | Per unit by zone, with 10% off at 10 units and 15% off at 25. Pickup towns only. |
GET /v1/catalog (scope network:read) lists the large items and bulk units with their keys. Cache it for a day.
Pickup and cover
Your parcels are collected together on one pickup run, so ordinary parcels pay no pickup fee. Large items and bulk loads need a vehicle and carry a pickup fee by distance from our hub. The first KES 5,000 of declared value is covered free; above that, cover is charged on the value over KES 5,000.
When we price it by hand
Some parcels cannot be priced online: three-seater sofas, beds, side-by-side fridges, anything declared above KES 300,000, and bulk loads over 50 units or 1,000 kg. These come back with "requires_quote": true, a quote_reason and null prices. Do not charge your customer a SendWay rate for that cart. Booking it returns 409 quote_required; send it as a quote request instead and our team will price it.
How size and weight interact
Send both. A parcel is billed at whichever implies the larger tier, so a small box declared at 25 kg is priced as bulky, not small.
| Size | Up to |
|---|---|
S | 2 kg |
M | 5 kg |
ML | 10 kg |
L | 20 kg |
BULKY | over 20 kg, or oversized |
When a route cannot be priced
A 422 with not_quotable means the route is outside the network, usually a destination we do not serve. category_not_available means a large item or bulk load was sent to a Nairobi address. Fall back to your own shipping method rather than blocking the checkout.
Next: booking the parcel.
