Quotes

A quote tells you the price and the pickup and delivery times for a package between two addresses. It is valid for 24 hours and books one delivery.

Create a quote

POST /quotes

Field	Type	Description
pickup_address_id or pickup	string or object	required (one of the two). A saved address id, or the address inline with the same fields as POST /addresses (name, phone, address, place_id, latitude and longitude, notes). An inline address is saved and its id returned.
dropoff_address_id or dropoff	string or object	required (one of the two). As for the pickup.
package	object	required. description (required, what it is), quantity (default 1), weight_kg, declared_value (in kobo), and dimensions_cm (optional: length, width, height in cm). See What Reeds carries.
pickup_date	date	Default today. Up to 7 days ahead, as YYYY-MM-DD.

curl https://api.getreeds.co/shipping/v1/quotes \
  -H "Authorization: Bearer $REEDS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup_address_id": "adr_7Hq2Lk9P",
    "dropoff_address_id": "adr_5Vb1Jc8D",
    "package": {
      "description": "2 pairs of sneakers",
      "quantity": 1,
      "weight_kg": 1.5,
      "declared_value": 4500000
    }
  }'

Response 201

{
  "status": "success",
  "data": {
    "id": "qt_2bX9Wn4K",
    "available": true,
    "livemode": false,
    "expires_at": "2026-10-27T10:20:00+01:00",
    "pickup_address_id": "adr_7Hq2Lk9P",
    "dropoff_address_id": "adr_5Vb1Jc8D",
    "service": "standard",
    "route": { "type": "via_hub", "distance_km": 13.5 },
    "fee": {
      "delivery_fee": 255000,
      "vat": 19125,
      "service_charge": 5875,
      "discount": 0,
      "total": 280000,
      "currency": "NGN"
    },
    "schedule": {
      "pickup_by": "2026-10-26T19:00:00+01:00",
      "deliver_by": "2026-10-27T19:00:00+01:00",
      "earliest_delivery": "2026-10-26T19:00:00+01:00"
    },
    "package": { "description": "2 pairs of sneakers", "quantity": 1, "weight_kg": 1.5, "declared_value": 4500000 }
  }
}

The fee

All amounts are integers in kobo, with currency: "NGN".

Field	Meaning
delivery_fee	The price for the distance tier
vat	7.5% VAT on the delivery fee
service_charge	What the total is rounded up by (see below)
discount	Any discount that applies. 0 if none.
total	What you pay. Always equals the booked charge.

The total is the delivery fee plus VAT, rounded up to the next ₦50, with at least ₦25 of that rounding kept as the service charge.

Worked example. A delivery fee of 255000 kobo (₦2,550) plus 7.5% VAT of 19125 gives 274125. The next ₦50 step is 275000, but that leaves only 875 kobo of rounding, below the ₦25 minimum (2500 kobo). So the total steps up to 280000 (₦2,800), and the service charge is 280000 minus 274125, which is 5875.

An account with a rate card gets its own price from the same structure.

Service and route

• service is standard (within a state, a two-day range) on every quote and delivery the API returns. interstate is reserved for inter-state delivery, which is not available through the API. Reeds may add services later, so tolerate values you don't know.
• route.type is direct (under 7 km: one rider, no hub) or via_hub (collected into the nearest Reeds hub, then delivered). route.distance_km is the distance used for pricing.

Schedule

Field	Description
schedule.pickup_by	When Reeds will have collected the parcel
schedule.earliest_delivery	The first day of the delivery range. Use only the date. The time is always 19:00 (close of business), but the parcel can arrive at any time that day.
schedule.deliver_by	The last day of the delivery range: when Reeds will have delivered it

Times are ISO 8601 with the Lagos offset (+01:00). See Delivery promise.

A quote's schedule is what Reeds promises if you book it now. The delivery's own schedule is worked out again when it is booked and ready. So on a weekday, a quote made at 10:00 and booked at 15:00, after the 13:45 cut-off, gets the next working day's range. The price doesn't change.

Validity and locked price

A quote lasts 24 hours (see expires_at) and books one delivery. The price is locked when quoted: booking within 24 hours pays exactly the quoted total.

Error	HTTP	Meaning
QUOTE_EXPIRED	409	The quote is older than 24 hours. Quote again.
QUOTE_ALREADY_USED	409	The quote already booked a delivery. error.delivery_id is the delivery this quote booked.

When Reeds can't serve the route

An unavailable route is not an error. You get HTTP 200 with available: false and a reason, so a platform that asks every courier at once can simply leave Reeds out.

Response 200, unavailable

{
  "status": "success",
  "data": {
    "available": false,
    "reason": { "code": "ADDRESS_NOT_SERVICEABLE", "message": "The drop-off is outside Reeds' coverage" },
    "pickup_address_id": "adr_7Hq2Lk9P",
    "dropoff_address_id": "adr_6Tn3Wd5R"
  }
}

reason.code	When
ADDRESS_NEEDS_CONFIRMATION	An address matched only approximately, or not at all. data.suggestion is Reeds' best match (null if there is none). Quote again with coordinates or a place id, or create a draft.
ADDRESS_NOT_SERVICEABLE	An address is outside Reeds' coverage, or there is no road route between the two
INTERSTATE_NOT_AVAILABLE	The drop-off is in another state. Inter-state delivery is not available through the API.

What Reeds carries

Reeds checks the package when you quote and when you create a draft. Each limit has its own 422 error.

• One parcel weighs up to 30 kg (PARCEL_TOO_HEAVY).
• Its longest side is up to 120 cm (PARCEL_TOO_LARGE). Send package.dimensions_cm so Reeds can check it.
• Reeds never carries cash, weapons, drugs, hazardous goods (fuel, gas cylinders, explosives, chemicals) or perishable food (PROHIBITED_ITEM). The check reads package.description, so describe items precisely ("glue gun", not "gun").
• Reeds covers loss or damage up to declared_value, at most ₦50,000 per delivery. A higher declared value is accepted, but it isn't covered above ₦50,000. The delivery's liability shows what is covered.

Speed

Platforms show the price at checkout, so the target is an answer within 2 seconds for 95% of quotes.

Send coordinates or a place id

If you already hold coordinates or a Google place id, send them. A text-only address that matches only approximately makes the quote unavailable, and Reeds drops out of that checkout. See Checkout quotes.

Next steps

• Book a delivery
• Drafts and required actions
• Rate limits: quotes have their own limit