Order food, groceries, cargo and more, all in the BikesDrop app.Riders: go online and start earning with BikesDrop today.Merchants: list your store on BikesFood or BikesGroceries in minutes.BikesDrop is open for investment and partnership. Talk to our team.
Learn more
Back to siteDelivery Integration

API Documentation

Pickup Delivery Vendor API — base URL https://us-central1-pharmaghana-913f6.cloudfunctions.net

Don't have an account yet? Sign up to get your own test keys, or sign in if you already have one.

Authentication

Every endpoint requires HTTP Basic authentication — your key as the username, your secret as the password. Your secret is stored hash-only on our end, never as plaintext, so we can never show it to you again after you generate it; losing it means regenerating, not recovering.

Authorization: Basic base64("pk_test_xxx:sk_test_xxx")

A test_ key pair never creates a real delivery or pages a real rider. A live_ key requires identity verification to generate.

This is a plain REST API — no SDK, no language requirement. Anything that can make an HTTPS request and do HTTP Basic auth works: curl, Node.js, Python, PHP, Ruby, Java, Go, C#, whatever you already use on your own server. curl's -u, Python's requests, and most HTTP clients' basic-auth option build that header for you — you never need to base64-encode it by hand.

POST /apiVendorQuote

Get a price for a pickup → dropoff pair. Quotes expire after 5 minutes.

{
  "pickupLat": 5.6037, "pickupLng": -0.1870,
  "dropoffLat": 5.5900, "dropoffLng": -0.2000
}

Response:

{
  "quoteId": "a1b2c3…",
  "price": 18.50,
  "currency": "GHS",
  "distanceKm": 3.2,
  "durationSeconds": 540,
  "expiresAt": 1699999999999
}
curl -X POST https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorQuote \
  -u "pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"pickupLat":5.6037,"pickupLng":-0.1870,"dropoffLat":5.5900,"dropoffLng":-0.2000}'

GET /apiVendorRidersAvailable

How many online riders are within your configured radius of your registered business location.

{ "availableRiders": 14, "radiusKm": 10 }
curl -u "pk_test_xxx:sk_test_xxx" https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorRidersAvailable

POST /apiVendorCreateDelivery

Book a delivery against a quote. idempotencyKey should be unique per booking attempt — a retried call with the same key returns the existing delivery instead of creating a duplicate. Broadcast only: there's no way to choose a specific rider.

{
  "quoteId": "a1b2c3…",
  "idempotencyKey": "order-42-attempt-1",
  "vendorOrderId": "order-42",
  "pickup":  { "address": "…", "lat": 5.6037, "lng": -0.1870, "contactName": "…", "contactPhone": "…" },
  "dropoff": { "address": "…", "lat": 5.5900, "lng": -0.2000, "contactName": "…", "contactPhone": "…" },
  "package": { "size": "medium", "weightRange": "1-5kg", "description": "…" }
}

Response:

{
  "deliveryId": "…", "trackingCode": "BIKESDROPXXXXXX",
  "trackingUrl": "https://bikesdrop.com/track/BIKESDROPXXXXXX",
  "status": "pending", "price": 18.50
}

402 if your balance can't cover the quote — there's no postpaid option.

curl -X POST https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorCreateDelivery \
  -u "pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "a1b2c3…",
    "idempotencyKey": "order-42-attempt-1",
    "vendorOrderId": "order-42",
    "pickup":  { "address": "…", "lat": 5.6037, "lng": -0.1870, "contactName": "Your Kitchen", "contactPhone": "0240000000" },
    "dropoff": { "address": "…", "lat": 5.5900, "lng": -0.2000, "contactName": "Customer Name", "contactPhone": "0240000001" }
  }'

GET /apiVendorGetDelivery?id=…

Current status, scoped to your own deliveries only.

{
  "deliveryId": "…", "vendorOrderId": "order-42",
  "status": "picked", "trackingCode": "…", "trackingUrl": "…",
  "price": 18.50,
  "rider": { "name": "John A.", "phone": "0240000067" }
}

rider is null before a rider accepts, and once the delivery is delivered or cancelled. The phone is the rider's real number, so you can call them directly if you need to — a wrong order, a redirect, a gate code they can't get past.

curl -u "pk_test_xxx:sk_test_xxx" "https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorGetDelivery?id=$DELIVERY_ID"

GET /apiVendorDeliveries

List your own recent deliveries, newest first — enough to build a deliveries table on your own dashboard without tracking every id yourself. Optional limit (default 20, max 100) and before (the previous page's nextBefore, for paging further back) query params. A test_ key only ever lists test bookings; a live_ key only ever lists real ones.

{
  "deliveries": [
    { "deliveryId": "…", "vendorOrderId": "order-42", "status": "delivered",
      "trackingCode": "…", "trackingUrl": "…", "price": 18.50, "createdAt": 1699999999999 },
    …
  ],
  "nextBefore": 1699999800000
}

nextBefore is null once you've reached the last page.

curl -u "pk_test_xxx:sk_test_xxx" "https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorDeliveries?limit=20"

GET /apiVendorBalance

Your current prepaid balance — enough to show it on your own dashboard without logging into BikesDrop's.

{ "balance": 452.30, "currency": "GHS" }
curl -u "pk_test_xxx:sk_test_xxx" https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorBalance

Funding the wallet itself still only happens from the BikesDrop dashboard — moving real money requires your account's own login session, not an API key, so it isn't part of this REST API.

POST /apiVendorCancelDelivery?id=…

Free before a rider accepts, free within the free window after acceptance, a fee after that — and a fee always applies once the rider has picked up (admin-configured; can be the full fare, since prepared food usually can't be meaningfully returned). The unused portion of the original charge is refunded to your balance automatically.

{ "cancelled": true, "feePercent": 20, "feeAmount": 3.70, "refundAmount": 14.80 }
curl -X POST -u "pk_test_xxx:sk_test_xxx" "https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorCancelDelivery?id=$DELIVERY_ID"

GET /apiVendorCancellationPolicy

The live fee schedule above, as numbers — admin-configurable, so don't hardcode these in your own integration. Check this before cancelling to show your own customer the right number up front, rather than only finding out the fee after the fact from apiVendorCancelDelivery's own response.

{ "freeWindowMinutes": 5, "feePercentAfterFreeWindow": 20, "feePercentAfterPickup": 100 }
curl -u "pk_test_xxx:sk_test_xxx" https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorCancellationPolicy

POST /apiVendorVerifyPickupPin?id=…

Before handing a package to the rider, ask them for the 6-digit pickup PIN BikesDrop sent them and submit it here — a correct match confirms this is really the assigned rider and returns their name, plate number, and photo. 5 attempts per code before it locks; each code is only live until that delivery's handover.

{ "pin": "482913" }

Response:

{
  "verified": true,
  "rider": { "name": "John A.", "plateNumber": "GR-1234-24", "photoUrl": "https://…" }
}
curl -X POST -u "pk_test_xxx:sk_test_xxx" "https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorVerifyPickupPin?id=$DELIVERY_ID" \
  -H "Content-Type: application/json" \
  -d '{"pin":"482913"}'

Webhook

We POST a signed event to your registered URL on every status change. Verify it with HMAC-SHA256 over the string {timestamp}.{rawBody} using your webhook signing secret (shown once, at registration).

X-BikesDrop-Signature: t=1699999999999,v1=<hex hmac>
{
  "type": "delivery.status_changed",
  "deliveryId": "…", "vendorOrderId": "order-42",
  "status": "picked", "trackingUrl": "…",
  "rider": { "name": "John A.", "phone": "0240000067" }
}

Retries on 5xx/timeout only: first retry ~10s later, then 30s, 3 attempts total. After that, reconcile via GET /apiVendorGetDelivery — we never retry forever, and a persistently failing webhook never pauses future events, so a fixed endpoint self-heals with nothing to re-enable.

Verifying a received event — use your framework's raw request body, not a re-serialized/parsed one, or the hash won't match:

const crypto = require('crypto');

function isValidSignature(rawBody, signatureHeader, signingSecret) {
  const [tPart, vPart] = signatureHeader.split(',');
  const timestamp = tPart.split('=')[1];
  const signature = vPart.split('=')[1];
  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Rate limits

Per key, per minute: 60 quote, 60 riders-available, 20 book, 120 status, 20 cancel, 60 deliveries list, 120 balance, 30 pickup PIN verification, 120 cancellation policy. A 429 means slow down, not that anything is wrong.