Requests and responses

Every endpoint takes and returns JSON with snake_case field names. Send Content-Type: application/json on requests with a body and Authorization: Bearer <access_token> on every request.

Success envelope

A successful response wraps the result in data:

Response 200
{
  "status": "success",
  "data": {
    "id": "dlv_9Kd3Qx7M",
    "status": "picked_up",
    "...": "other delivery fields"
  }
}

List envelope

Lists return an array in data, plus has_more:

Response 200
{
  "status": "success",
  "data": [
    { "id": "dlv_8Pq4Ns2L", "...": "a delivery object" },
    { "id": "dlv_7Hn2Lk1C", "...": "a delivery object" }
  ],
  "has_more": true
}

See Pagination.

Failure envelope

A failed request returns status: "failed" and an error object:

Response 409
{
  "status": "failed",
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "The quote is older than 24 hours",
    "doc_url": "https://developer.getreeds.co/errors/QUOTE_EXPIRED",
    "fields": []
  }
}

Field	Description
`code`	A stable, machine-readable code. Branch on this.
`message`	A human-readable explanation. It can change, so never branch on it.
`doc_url`	A link to the error's page on this site.
`fields`	On `422 INVALID_REQUEST` and `PICKUP_DATE_OUT_OF_RANGE`, one entry per field at fault. Otherwise an empty array.

See Errors.

A blocked delivery is not an error

A delivery that is created but can't move yet, such as a draft with an address to confirm, returns 201 with status: requires_action. It is a success. Read required_actions to see what to do.

Request ids

Every response carries an X-Request-Id header. Every call appears in Dashboard → Developers → API requests for 30 days, with its X-Request-Id, so quote that id to support when you need help with a call.

Ids

Ids are opaque, prefixed strings. Store them as text and don't parse them. Real ids are longer than the examples on this site, so allow 64 characters.

Prefix	Object	Example
`adr_`	Address	`adr_7Hq2Lk9P`
`qt_`	Quote	`qt_2bX9Wn4K`
`dlv_`	Delivery	`dlv_9Kd3Qx7M`
`txn_`	Wallet transaction	`txn_Hd5Rw2Zx`
`inv_`	Invoice	`inv_6Gc4Yt8N`
`evt_`	Webhook event	`evt_4fQ7Hd2X`

Each delivery also has a tracking_code (for example HQ3W5F2), the id your customers see, and a tracking_url (https://getreeds.co/packages/HQ3W5F2).

Money

Money is an integer in kobo, with currency: "NGN". Never use decimals. ₦2,800.00 is 280000.

{
  "delivery_fee": 255000,
  "vat": 19125,
  "service_charge": 5875,
  "discount": 0,
  "total": 280000,
  "currency": "NGN"
}

Times and dates

Times are ISO 8601 with the Lagos offset, for example 2026-10-26T13:05:00+01:00. Dates are YYYY-MM-DD.

Metadata

Addresses and deliveries accept up to 20 string key/value pairs in metadata. Reeds returns them in responses and webhooks, so you can keep your own ids with Reeds objects.

{ "metadata": { "store_id": "42", "order_id": "10045" } }

HTTP status codes

Code	Meaning
`200`	Read or update succeeded
`201`	Created (including a draft that needs action)
`400`	Malformed request: bad JSON, or a required header missing
`401`	Missing, invalid, expired or revoked access token
`402`	Not enough wallet balance, or credit limit reached
`403`	Not allowed: the account is on hold, the token lacks the scope, the IP is not on your live allowlist, or a live token came from a browser or called a sandbox endpoint
`404`	Not found. Another account's id also returns `404`.
`409`	Conflicts with the current state: quote expired or used, cancel too late, idempotent request still running
`422`	Validation failed; `error.fields` lists each problem
`429`	Rate limit reached
`500`	Reeds error
`503`	A service Reeds depends on (maps, payments) is unavailable; retry later

Success envelope​

List envelope​

Failure envelope​

Request ids​

Ids​

Money​

Times and dates​

Metadata​

HTTP status codes​

Next steps​