Business Deliveries
Business Deliveries API
Send deliveries to Ridelivo drivers from your own software: a hotel desk system, an online store, a courier portal. JSON over HTTPS. One call books a delivery; a batch becomes driver runs with the route already planned; webhooks tell you when a driver is assigned, when the parcel left and when it was delivered.
No software? The same account works from the Business portal on your phone: type or paste a list and we do the rest. Read about the service on Business Deliveries.
What it is
A business account belongs to a normal Ridelivo account (the owner’s) and adds members, a default pickup (your address, map pin and “find us” directions, shown to the driver on every job), API keys and webhooks. It pays from the business wallet (topped up by card or at a top-up shop) or the recipient pays cash on delivery.
Every delivery is a normal Ridelivo courier job: the same drivers, the same matching, the recipient PIN, the drop-off photo, the same receipts. It is priced as that job — your pickup to that drop-off by road, at the courier rate card, plus any toll on the route. There is no separate API price. All prices in this API are Jamaican dollars in cents: 142000 means J$1,420.
A batch is many deliveries from your pickup in one call. We find each address, price each stop, group the stops into runs (one driver, stops in order, by road time from our own map server) and show you the plan before anything is booked. A run is offered to one driver, so recipients are never shuffled between cars.
Getting a key
- Apply at ridelivo.com/business/portal with your normal Ridelivo sign-in: business name, type, pickup on the map, phone. Ridelivo staff approve the account (usually the same day).
- Set the pickup address and directions under Settings, and top up the wallet (or plan to use cash on delivery).
- The business owner opens API & webhooks and creates a key. The key (
rb_live_…, 40 characters) is shown once; only a fingerprint is kept on our side. Copy it into your software’s secret store. Up to 5 active keys; revoke one any time. - A key has permissions:
read,deliveries,batches. A key with fewer permissions getsSCOPE(403) on the calls it may not make.
There is no sandbox. Test with a real delivery to yourself and cancel it while it is still pending (free), or use POST /quotes, which books nothing.
Base URL, auth, idempotency
Base URL: https://ridelivo.com/api/business/v1/. Every call sends the key in the Authorization header and JSON bodies with Content-Type: application/json. Answers are JSON. Times are ISO 8601 in UTC.
Authorization: Bearer rb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/jsonThe calls, and the key permission each one needs:
| Call | Permission | What it does |
|---|---|---|
| GET /me | read | Your business, pickup, wallet balance and limits. |
| POST /quotes | read | Price and time for one delivery. Nothing is booked. |
| POST /deliveries | deliveries | Book one delivery. Idempotent on externalRef or Idempotency-Key. |
| GET /deliveries | read | Your deliveries, newest first (filter by status, batchId). |
| GET /deliveries/{id} | read | One delivery with its driver and timeline. |
| POST /deliveries/{id}/cancel | deliveries | Cancel. Free while still searching; the normal cancel rules after a driver accepted. |
| POST /batches | batches | Many deliveries from your pickup. confirm false = the plan only; confirm true = book it. |
| GET /batches/{id} | read | The batch, its runs (driver, status) and every delivery. |
| GET /webhooks · POST /webhooks · DELETE /webhooks/{id} | read · deliveries · deliveries | Where we send events (at most 3). |
| GET /events | read | The same events, to poll when you cannot receive webhooks. |
Never book twice. A retry after a timeout must not create a second job. Send your own order number as externalRef on POST /deliveries: the same reference always answers the same delivery (with "replayed": true). If you have no reference, send an Idempotency-Key header with any unique text (an order id, a UUID). POST /batches with confirm: true takes the Idempotency-Key header the same way. The same key with a different body answers IDEMPOTENCY_CONFLICT (409).
GET /me
The business this key belongs to, its pickup, the usable wallet balance (balance minus holds) and the current limits. A good first call to check a key works.
GET https://ridelivo.com/api/business/v1/me
200
{
"business": {
"id": "6d9a1f3e-…", "name": "Albert Town Bakery", "kind": "store", "status": "active",
"pickup": { "lat": 18.2886, "lng": -77.5497, "name": "Albert Town Bakery",
"address": "Main Street, Albert Town", "directions": "Blue gate beside the post office" }
},
"key": { "id": "…", "scopes": ["deliveries", "batches", "read"] },
"walletCents": 1250000,
"limits": { "max_stops_per_run": 8, "max_batch_stops": 60, "max_deliveries_per_day": 200, "key_calls_per_minute": 120 },
"deliveriesLast24h": 14
}POST /quotes
The price and road time of one delivery, with nothing booked. The body is the same as POST /deliveries; the recipient and item may be left out. Send a pin (dropoff.lat, dropoff.lng) or an address. estimated: true means our road router could not be reached and the distance is an estimate; the delivery is still charged by the meter at the end. Add scheduledPickupAt to price a later pickup (night rates apply by the pickup time).
POST https://ridelivo.com/api/business/v1/quotes
{
"dropoff": { "lat": 18.3365, "lng": -77.4985 }
}
— or —
{ "address": "Clark's Town square, Trelawny" }
200
{
"quote": { "priceCents": 70000, "km": 11.4, "minutes": 19, "tollCents": 0, "estimated": false, "basis": "zone", "zone": { "key": "town", "label": "Town" }, "retailCents": 142000 },
"dropoff": { "lat": 18.3365, "lng": -77.4985, "address": "Clark's Town, Trelawny" },
"pickup": { "lat": 18.2886, "lng": -77.5497 },
"currency": "JMD"
}POST /deliveries
Books one delivery from your pickup. Needs the deliveries permission. The answer is 201 with the delivery and the quote it was priced on, or 200 with "replayed": true when the same externalRef / Idempotency-Key was already booked.
| Field | Required | What it is |
|---|---|---|
| recipient.name | yes | Who receives it (2–120 characters). |
| recipient.phone | yes | A phone the driver can call (Jamaican numbers; 7–30 characters). |
| dropoff.lat, dropoff.lng | one of these | A map pin in Jamaica. The most reliable way. |
| address (or dropoff.address) | one of these | Address text. We look it up on our own map near your pickup; if we cannot find it you get ADDRESS_NOT_FOUND and nothing is booked. With a pin, the address is only shown to the driver. |
| item | yes | What is being delivered (2–500 characters). Shown to the driver and on the receipt. |
| parcelSize | no | small (fits a bag, default), medium (a box) or large (bulky; never offered to bikes). |
| paymentMethod | no | wallet (your business wallet pays, default) or cash (the recipient pays the driver on delivery). |
| notes | no | Drop-off directions for the driver (up to 500 characters). |
| externalRef | no, but recommended | Your own order number (1–120 characters), unique per business. The same value never books twice. |
| scheduledPickupAt | no | ISO 8601 time at least 20 minutes from now, to send later. Leave it out to send now. |
| earliestMin, latestMin | no (batches) | A delivery window in minutes from now. Used only to order the stops of a run. |
{
"externalRef": "ORDER-10421",
"recipient": { "name": "Kemar Brown", "phone": "876-555-1234" },
"dropoff": { "lat": 18.3365, "lng": -77.4985, "address": "12 Main Street, Clark's Town" },
"item": "Box of pastries",
"parcelSize": "small",
"paymentMethod": "wallet",
"notes": "Ring the bell at the side gate"
}201
{
"delivery": {
"id": "b3f2…", "externalRef": "ORDER-10421", "status": "pending", "held": false,
"requestNumber": 20261118000123, "batchId": null, "runId": null, "stopOrder": null,
"recipient": { "name": "Kemar Brown", "phone": "876-555-1234" },
"dropoff": { "lat": 18.3365, "lng": -77.4985, "address": "12 Main Street, Clark's Town" },
"item": "Box of pastries", "parcelSize": "small", "paymentMethod": "wallet",
"priceCents": 142000, "finalCents": null,
"driver": null, "proofPhoto": false,
"createdAt": "2026-11-18T14:02:11Z", "assignedAt": null, "pickedUpAt": null, "deliveredAt": null, "cancelledAt": null,
"scheduledPickupAt": null
},
"replayed": false,
"quote": { "priceCents": 142000, "km": 11.4, "minutes": 19, "tollCents": 0, "estimated": false }
}
Sending the same externalRef again answers 200 with "replayed": true and the SAME delivery.With paymentMethod: "wallet" the price is held on the business wallet when the delivery is booked and settled when it is delivered; INSUFFICIENT_WALLET_FUNDS (402) means the wallet does not cover it. With "cash" the driver collects the price from the recipient.
Creating a delivery: curl, JavaScript, PHP
Keep the key out of your code (an environment variable or your secret store). Read the status code: 2xx is a delivery; anything else has error.code and error.message.
curl
curl -X POST https://ridelivo.com/api/business/v1/deliveries \
-H "Authorization: Bearer rb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-d '{
"externalRef": "ORDER-10421",
"recipient": { "name": "Kemar Brown", "phone": "876-555-1234" },
"dropoff": { "lat": 18.3365, "lng": -77.4985, "address": "12 Main Street, Clark\u0027s Town" },
"item": "Box of pastries",
"parcelSize": "small",
"paymentMethod": "wallet"
}'JavaScript (Node 18+ or a browser-less runtime, fetch)
const res = await fetch('https://ridelivo.com/api/business/v1/deliveries', {
method: 'POST',
headers: {
'Authorization': 'Bearer ' + YOUR_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
externalRef: 'ORDER-10421',
recipient: { name: 'Kemar Brown', phone: '876-555-1234' },
dropoff: { lat: 18.3365, lng: -77.4985, address: "12 Main Street, Clark's Town" },
item: 'Box of pastries',
parcelSize: 'small',
paymentMethod: 'wallet',
}),
});
const body = await res.json();
if (!res.ok) throw new Error(body.error.code + ': ' + body.error.message);
console.log(body.delivery.id, body.delivery.status, body.quote.priceCents / 100);PHP (cURL)
<?php
$payload = [
'externalRef' => 'ORDER-10421',
'recipient' => ['name' => 'Kemar Brown', 'phone' => '876-555-1234'],
'dropoff' => ['lat' => 18.3365, 'lng' => -77.4985, 'address' => "12 Main Street, Clark's Town"],
'item' => 'Box of pastries',
'parcelSize' => 'small',
'paymentMethod' => 'wallet',
];
$ch = curl_init('https://ridelivo.com/api/business/v1/deliveries');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('RIDELIVO_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$body = json_decode($raw, true);
if ($status >= 400) {
throw new Exception($body['error']['code'] . ': ' . $body['error']['message']);
}
echo $body['delivery']['id'], ' ', $body['delivery']['status'], ' J$', $body['quote']['priceCents'] / 100;GET /deliveries
Your deliveries, newest first. Filter by status (use open for everything not yet delivered or cancelled) and by batchId.
GET https://ridelivo.com/api/business/v1/deliveries?status=open&limit=50
GET https://ridelivo.com/api/business/v1/deliveries?batchId=…
GET https://ridelivo.com/api/business/v1/deliveries?status=completed
200
{ "deliveries": [ { …delivery… }, … ] } (newest first)
status: open (anything not delivered or cancelled) | pending | driver_assigned | accepted |
driver_arriving | arrived | in_progress | completed | cancelled | (empty = all)
limit: 1–300, default 100GET /deliveries/{id}
One delivery with its driver (first name, plate, vehicle; never the driver’s phone) and the timeline of status changes. proofPhoto: true means the driver took a drop-off photo; staff can show it to you from the receipt if a recipient disputes a delivery.
GET https://ridelivo.com/api/business/v1/deliveries/b3f2…
200
{
"delivery": {
…the same fields as above…,
"driver": { "firstName": "Andre", "plate": "PP 1234", "vehicle": "White Toyota Probox" },
"timeline": [
{ "status": "pending", "at": "2026-11-18T14:02:11Z" },
{ "status": "driver_assigned", "at": "2026-11-18T14:03:40Z" },
{ "status": "in_progress", "at": "2026-11-18T14:21:05Z" },
{ "status": "completed", "at": "2026-11-18T14:44:52Z" }
]
}
}POST /deliveries/{id}/cancel
Cancels a delivery. Free while it is still pending (searching for a driver, or waiting in a run). After a driver accepted, the normal Ridelivo cancel rules and fees apply, the same as for any courier job. Cancelling an already delivered or cancelled delivery answers it unchanged.
POST https://ridelivo.com/api/business/v1/deliveries/b3f2…/cancel
{ "reason": "Customer changed their mind" }
200
{ "delivery": { …, "status": "cancelled", "cancelledAt": "2026-11-18T14:05:00Z" } }POST /batches
Many deliveries from your pickup in one call (permission batches). Send a list of deliveries (the same fields as POST /deliveries) or plain text, one delivery per line. With confirm: false (the default) you get the plan: runs, stops in order, drive time, km, the price of every stop and the total. With confirm: true the plan is booked.
How the plan is made: stops without a pin are found on our own map near your pickup; each stop is priced as its own courier job (pickup to that stop, never the detour); the road times between every point come from our map server; stops are grouped by direction and distance into runs of up to 8 stops and about 2 hours of driving (3 stops for a bicycle), and each run is put in the best order (exact up to 10 stops). A delivery window (earliestMin, latestMin) is honoured when given; a stop that would still be late is named under warnings.
Plan only (confirm false)
POST https://ridelivo.com/api/business/v1/batches
{
"confirm": false,
"deliveries": [
{ "externalRef": "ORD-1", "recipient": { "name": "Kemar Brown", "phone": "876-555-1234" },
"dropoff": { "lat": 18.3365, "lng": -77.4985 }, "item": "Box of pastries" },
{ "externalRef": "ORD-2", "recipient": { "name": "Shanice Reid", "phone": "876-555-9876" },
"address": "Wait-a-Bit, Trelawny", "item": "Birthday cake", "parcelSize": "medium", "paymentMethod": "cash" },
{ "externalRef": "ORD-3", "recipient": { "name": "Mr. Chin", "phone": "876-555-4444" },
"address": "Christiana square", "item": "Bread order" }
]
}
200
{
"confirmed": false,
"plan": {
"pickup": { "lat": 18.2886, "lng": -77.5497 },
"stops": 3, "plannable": 3, "totalCents": 389000, "km": 38.2, "minutes": 71, "matrixSource": "road",
"warnings": [],
"problems": [],
"runs": [
{ "seq": 1, "stops": 2, "km": 24.1, "minutes": 43, "method": "exact",
"list": [
{ "id": "s1", "order": 1, "etaMin": 19, "legKm": 11.4, "directKm": 11.4, "recipientName": "Kemar Brown",
"address": "Clark's Town, Trelawny", "item": "Box of pastries", "priceCents": 142000, "externalRef": "ORD-1", "paymentMethod": "wallet" },
{ "id": "s2", "order": 2, "etaMin": 41, "legKm": 12.7, "directKm": 9.8, "recipientName": "Shanice Reid",
"address": "Wait-a-Bit, Trelawny", "item": "Birthday cake", "priceCents": 128000, "externalRef": "ORD-2", "paymentMethod": "cash" }
] },
{ "seq": 2, "stops": 1, "km": 14.1, "minutes": 28, "method": "trivial", "list": [ { "id": "s3", … } ] }
]
}
}
A stop with a problem (address not found, outside Jamaica, missing phone) is listed under "problems" with the
reason and left OUT of the runs, so you can fix it and plan again. Nothing is booked with confirm false.Book it (confirm true)
POST https://ridelivo.com/api/business/v1/batches
Idempotency-Key: 2026-11-18-morning-run
{ "confirm": true, "note": "Morning orders", "deliveries": [ …the same list… ] }
201
{
"confirmed": true,
"batchId": "9c1e…",
"runIds": [ "5a7b…", "5a7c…" ],
"deliveries": [ { …delivery… }, { …delivery… }, { …delivery… } ],
"plan": { …the plan that was booked… }
}
Every stop became a delivery (its own courier job, its own price). Each run is offered to ONE driver: the first stop
goes to matching, the other stops wait and go to the same driver once they accept. Re-sending with the same
Idempotency-Key books nothing twice.The text form
POST https://ridelivo.com/api/business/v1/batches
{
"confirm": false,
"text": "Kemar Brown, 876-555-1234, 12 Main Street Clark's Town, Box of pastries\nShanice Reid, 876-555-9876, Wait-a-Bit, Birthday cake, call on arrival"
}
One delivery per line: Name, phone, address[, item][, note] (commas or tabs).
A CSV with a header row is read by its column names: name, phone, address, item, note, ref, lat, lng.What the driver sees: one offer for the whole run (“Business run · 6 parcels · <your business> → 6 stops · about 55 min”). Accepting puts every stop in their job list in order, with its own recipient, PIN and drop-off photo. If nobody accepts a run in time, Ridelivo Dispatch sees it and can split it or give it to a driver by hand.
GET /batches/{id}
The batch, each run with its driver and status, and every delivery (with runId and stopOrder).
GET https://ridelivo.com/api/business/v1/batches/9c1e…
200
{
"batch": {
"id": "9c1e…", "status": "confirmed", "stops": 3, "totalCents": 389000, "note": "Morning orders",
"createdAt": "…", "confirmedAt": "…",
"runs": [
{ "id": "5a7b…", "seq": 1, "status": "in_progress", "stops": 2, "km": 24.1, "minutes": 43,
"driver": { "firstName": "Andre", "plate": "PP 1234", "vehicle": "White Toyota Probox" },
"plan": [ { "deliveryId": "…", "order": 1, "etaMin": 19, "km": 11.4 }, … ] },
{ "id": "5a7c…", "seq": 2, "status": "searching", "stops": 1, "km": 14.1, "minutes": 28, "driver": null, "plan": [ … ] }
],
"plan": { …as shown before confirming… },
"deliveries": [ { …delivery…, "runId": "5a7b…", "stopOrder": 1 }, … ]
}
}
Run status: planned → searching → assigned → in_progress → done (or cancelled).Delivery statuses
The status of a delivery, in the order it normally moves. A delivery in a run shows held: true while it waits for the run’s first stop to get a driver; it is still pending.
| Status | Meaning | Event sent |
|---|---|---|
| pending | Finding a driver | delivery.created |
| awaiting_payment | Waiting for payment (rare: the payment is still being arranged; it moves on by itself) | — |
| driver_assigned | Driver assigned (staff or a run assigned the driver) | delivery.driver_assigned |
| accepted | Driver on the way to pickup | delivery.driver_assigned |
| driver_arriving | Driver arriving at pickup | delivery.driver_arriving |
| arrived | Driver at pickup | delivery.arrived |
| in_progress | On the way to the recipient | delivery.picked_up |
| completed | Delivered; finalCents is the final price | delivery.delivered |
| cancelled | Cancelled | delivery.cancelled |
Webhooks
Tell us an https:// address and which events you want; we POST each event there as it happens. Up to 3 webhooks per business. Creating one answers its secret once; the portal’s API & webhooks page shows the last success, the last error and the failure count of each.
| Event | When | |
|---|---|---|
| delivery.created | The delivery was booked (also for every stop of a confirmed batch). | |
| delivery.driver_assigned | A driver accepted it. "data.driver" has their first name, plate and vehicle. | |
| delivery.driver_arriving | The driver is close to your pickup. | |
| delivery.arrived | The driver is at your pickup. | |
| delivery.picked_up | The parcel left your pickup and is on its way to the recipient. | |
| delivery.delivered | Delivered (recipient PIN or drop-off photo). "data.finalCents" is the final price. | |
| delivery.cancelled | Cancelled by you, the recipient, the driver or Ridelivo staff. | |
| batch.planned | A batch was confirmed: "data" has batchId, stops, runs and totalCents. |
GET https://ridelivo.com/api/business/v1/webhooks
200
{ "webhooks": [ { "id": "…", "url": "https://example.com/ridelivo", "events": [ … ], "active": true,
"createdAt": "…", "lastOkAt": "…", "lastError": null, "fails": 0 } ] }
POST https://ridelivo.com/api/business/v1/webhooks
{ "url": "https://example.com/ridelivo", "events": ["delivery.driver_assigned", "delivery.delivered", "delivery.cancelled"] }
201
{ "webhook": { "id": "…", "url": "https://example.com/ridelivo", "events": [ … ], "secret": "whsec_…" } }
↑ the secret is shown ONCE. Keep it; you need it to check signatures. Leave "events" out to get all of them.
DELETE https://ridelivo.com/api/business/v1/webhooks/{id}
200
{ "deleted": true }What we send
POST https://example.com/ridelivo
Content-Type: application/json
User-Agent: Ridelivo-Webhooks/1.0
X-Ridelivo-Event: delivery.delivered
X-Ridelivo-Delivery: 8841 (our attempt id; the same event id can arrive twice, use "id" to de-duplicate)
X-Ridelivo-Signature: t=1763478292,v1=5f1c…a9
{
"id": 1207,
"event": "delivery.delivered",
"createdAt": "2026-11-18T14:44:52Z",
"businessId": "6d9a1f3e-…",
"data": { …the delivery, same fields as GET /deliveries/{id} (no timeline)… }
}
Answer any 2xx within 8 seconds. Anything else is retried after 1 min, 5 min, 30 min, 2 h and 12 h (6 tries in all);
then it is marked failed and shows under API & webhooks in the portal.Events can arrive out of order or twice (a retry after a slow answer). Use the event id to ignore one you already handled, and data.status as the truth, not the order of arrival.
Checking the signature
Every call carries X-Ridelivo-Signature: t=<unix seconds>,v1=<hex>. v1 is the HMAC-SHA256, with your webhook secret, of the text <t>.<raw body> (the timestamp, a dot, the exact bytes of the body). Compute it, compare with a constant-time compare, and reject anything older than 5 minutes (|now − t| > 300 s) so a captured call cannot be replayed.
// Node.js (Express): keep the RAW body — the signature is over the exact bytes we sent.
const crypto = require('node:crypto');
function verifyRidelivo(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes: reject
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const got = String(parts.v1 || '');
return got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}
app.post('/ridelivo', express.raw({ type: 'application/json' }), (req, res) => {
if (!verifyRidelivo(req.body.toString('utf8'), req.get('X-Ridelivo-Signature') || '', YOUR_WEBHOOK_SECRET)) {
return res.status(401).end();
}
const event = JSON.parse(req.body.toString('utf8'));
// event.event = "delivery.delivered", event.data = the delivery
res.status(200).end(); // answer first, then do your work
});In PHP: hash_hmac('sha256', "$t.$rawBody", $secret) and hash_equals($expected, $v1); read the raw body with file_get_contents('php://input').
GET /events
The same events webhooks carry, to poll when your software cannot receive calls from the internet. Events are numbered in order; ask for everything after the last id you saw.
GET https://ridelivo.com/api/business/v1/events?since=1207&limit=100
200
{
"events": [
{ "id": 1208, "event": "delivery.driver_assigned", "createdAt": "…", "data": { …delivery… } },
{ "id": 1209, "event": "delivery.picked_up", "createdAt": "…", "data": { …delivery… } }
]
}
Remember the last "id" you saw and pass it as "since" next time. limit: 1–500, default 100.Errors
Every error answers a non-2xx status and this body. problems is present when more than one field is wrong (field says which).
{
"error": {
"code": "INVALID_DELIVERY",
"message": "Give a phone number for the recipient (the driver calls it).",
"problems": [
{ "field": "recipient.phone", "code": "RECIPIENT_PHONE", "message": "Give a phone number for the recipient (the driver calls it)." }
]
}
}| HTTP | Codes | Meaning |
|---|---|---|
| 400 | BAD_REQUEST, BUSINESS_COURIER_ONLY, INVALID_PAYMENT_METHOD, INVALID_URL, INVALID_EVENTS, PICKUP_REQUIRED, RUN_TOO_BIG | The request is malformed, or the business pickup is not set in the portal. |
| 401 | INVALID_KEY | No key, a wrong key, or a revoked key. |
| 402 | INSUFFICIENT_WALLET_FUNDS, OUTSTANDING_BALANCE | The business wallet does not cover the delivery (top it up, or use cash), or an earlier trip is unpaid. |
| 403 | BUSINESS_NOT_ACTIVE, ACCESS_DENIED, SCOPE | The business is pending, suspended or closed; or the key lacks the permission (read, deliveries, batches). |
| 404 | BUSINESS_NOT_FOUND, DELIVERY_NOT_FOUND, BATCH_NOT_FOUND, RUN_NOT_FOUND, NOT_FOUND, DRIVER_NOT_FOUND | Not yours, or no such id. |
| 409 | IDEMPOTENCY_CONFLICT, PROFILE_INCOMPLETE, TOO_MANY_WEBHOOKS, TOO_MANY_KEYS, DRIVER_OFFLINE | The same Idempotency-Key was used for a different body; or a limit (3 webhooks, 5 keys). |
| 422 | INVALID_DELIVERY, ADDRESS_NOT_FOUND, OUTSIDE_SERVICE_AREA, SCHEDULE_TOO_SOON, EMPTY, TOO_MANY, NOTHING_TO_BOOK | We understood the request but cannot book it: a field is missing or wrong ("problems" lists each one), the address was not found on the map, the pin is outside Jamaica, or no stop in the batch could be planned. |
| 429 | RATE_LIMITED, BUSINESS_DAILY_LIMIT | Too many calls for this key (wait a minute), or the deliveries-per-day limit of the business. |
| 503 | BUSINESS_OFF, BUSINESS_API_OFF, BUSINESS_BATCHES_OFF | That part of Business Deliveries is switched off right now. Try later or message us. |
| 500 | SERVER_ERROR | Our side. Safe to retry with the same externalRef / Idempotency-Key. |
Limits
- 120 calls a minute per key for reads, 60 a minute for writes (POST, DELETE). Over the limit:
RATE_LIMITED(429); wait a minute. - 200 deliveries a day per business by default (
BUSINESS_DAILY_LIMIT, 429). Message us to raise it. - 60 stops in one batch; runs of up to 8 stops by default (3 for a bicycle) and about 2 hours of driving. Bigger batches become more runs.
- Bodies up to 256 KB. Up to 5 active keys and 3 webhooks per business.
- Jamaica only. A pin outside Jamaica or an address we cannot find on the map is refused before anything is booked.
- A scheduled pickup needs at least 20 minutes’ notice.
- Recipient details are shown only to you, Ridelivo staff and the driver on that job, and are never shared with other partners.
Questions, a higher limit, or something missing you need? Write to us from the support page and say it is about the Business API.