Quickstart
- Open a YOBU business account (approved within a day).
- In the portal, go to API & integrations and create an API key.
- Call the API from your server:
curl https://hilnxbmieuogemjpiund.supabase.co/functions/v1/partner-api/v1/ping \
-H "Authorization: Bearer yobu_live_YOUR_KEY"
Base URL: https://hilnxbmieuogemjpiund.supabase.co/functions/v1/partner-api. All requests and responses are JSON. Prices are in US dollars.
Authentication
Send your key in the Authorization header: Bearer yobu_live_…. Keys are shown once when you create them; we only store a fingerprint. Never put a key in a web page or a mobile app: call the API from your server. If a key leaks, revoke it in the portal and create a new one.
Get a quote
curl -X POST $BASE/v1/quotes \
-H "Authorization: Bearer $YOBU_KEY" -H "Content-Type: application/json" \
-d '{
"service": "standard",
"pickup": { "address": "3100 St Paul St, Baltimore, MD 21218" },
"dropoff": { "address": "1 W Pennsylvania Ave, Towson, MD 21204" }
}'
{
"service": "standard",
"price": 15.12,
"currency": "USD",
"distance_miles": 5.9,
"duration_minutes": 17,
"eta": "2–4 hours",
"expires_in_minutes": 30
}
service: standard (2–4 h), express (about 90 min) or medical. The price uses the real driving route and your account discount.
Create a delivery
curl -X POST $BASE/v1/deliveries \
-H "Authorization: Bearer $YOBU_KEY" -H "Content-Type: application/json" \
-d '{
"external_id": "ORDER-1042",
"service": "standard",
"pickup": { "address": "3100 St Paul St, Baltimore, MD 21218", "name": "Front desk", "phone": "4105550100", "notes": "Ready at the counter" },
"dropoff": { "address": "1100 W 36th St, Baltimore, MD 21211", "name": "Jane Doe", "phone": "4105550123", "email": "jane@example.com", "notes": "Ring twice" },
"item": "Prescription bag",
"packages": 2,
"require_signature": true,
"items": [{ "name": "Bag A", "qty": 1 }, { "name": "Bag B", "qty": 1 }],
"scheduled_date": "2026-11-03",
"scheduled_time": "Afternoon"
}'
| Field | Required | Notes |
|---|---|---|
pickup.address, dropoff.address | yes | Full street address with city and state. |
dropoff.phone | yes | 10 digits. The recipient gets text updates and the driver can call. |
external_id | recommended | Your order number. Sending the same value twice returns the existing delivery (safe retries). You can also use an Idempotency-Key header. |
packages | no | 1–50. Print one YOBU label per package from the portal; drivers scan each one at pickup and at the door. |
require_signature | no | The driver must collect a signature before completing. |
items | no | Up to 80 lines {name, qty, barcode?}. Shown to the driver as a checklist. |
scheduled_date, scheduled_time | no | Empty = as soon as possible. |
Response 201: the delivery object. It includes tracking_url, a live tracking page you can send to your customer.
Get a delivery
{
"id": "YB-TDCRG2",
"external_id": "ORDER-1042",
"status": "on_the_way",
"service": "standard",
"price": 15.12,
"currency": "USD",
"distance_miles": 5.9,
"duration_minutes": 17,
"pickup": { "address": "3100 St Paul St, Baltimore, MD 21218" },
"dropoff": { "address": "1100 W 36th St, Baltimore, MD 21211", "name": "Jane Doe", "phone": "4105550123" },
"packages": 2,
"require_signature": true,
"driver": { "name": "Moussa", "location": { "lat": 39.31, "lon": -76.62, "updated_at": "2026-11-03T15:42:10Z" } },
"proof": null,
"tracking_url": "https://yobudelivery.com/track.html?o=YB-TDCRG2&t=…",
"created_at": "2026-11-03T15:01:44Z",
"delivered_at": null
}
When status is delivered, proof contains photo_url and signature_url.
List deliveries
Returns { "data": [ …delivery objects ] }, newest first (max 100).
Cancel a delivery
Possible while the status is pending or driver_assigned. Once the order is picked up, call us at (443) 425-8256.
Statuses
| Status | Meaning |
|---|---|
pending | Received, looking for the closest driver. |
driver_assigned | A driver accepted and is heading to the pickup. |
picked_up | The driver has the order (photo at pickup). |
on_the_way | Driving to the recipient. Live location is available. |
delivered | Delivered, with photo and signature when required. |
cancelled | Cancelled by you or by YOBU. |
Errors & limits
{ "error": { "code": "dropoff_not_found", "message": "We could not find the drop-off address. Add the city and state." } }
| HTTP | Codes |
|---|---|
| 401 | unauthorized missing, invalid or revoked key |
| 403 | account_inactive |
| 404 | not_found |
| 409 | duplicate, cannot_cancel |
| 422 | missing_fields, pickup_not_found, dropoff_not_found, no_route, out_of_area (over 100 miles) |
| 429 | rate_limited: 120 new deliveries per hour per account (ask us to raise it) |
Webhooks
Add your HTTPS endpoint in the portal (API & integrations → Webhook). We POST an event each time one of your deliveries changes status, and retry up to 3 times if your server does not answer with a 2xx.
POST https://yourdomain.com/yobu-webhook
YOBU-Event: delivery.delivered
YOBU-Signature: t=1793635210,v1=5f2c…
{
"id": "evt_8b1f…",
"type": "delivery.delivered",
"created_at": "2026-11-03T16:20:10Z",
"data": { …delivery object… }
}
Event types: delivery.created, delivery.driver_assigned, delivery.picked_up, delivery.on_the_way, delivery.delivered, delivery.cancelled, and delivery.test (from the portal's test button).
Verify the signature (Node.js)
import crypto from 'node:crypto';
// rawBody = the exact request body as a string (before JSON.parse)
export function verifyYobu(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; // 5-minute window
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ''));
}
Your signing secret starts with whsec_ and is shown in the portal when you save the webhook.
"Deliver with YOBU" button
No code on your server? Paste this on your website. Your customers book a same-day delivery from your store in a pop-up, without leaving your page. Get the exact snippet with your store address in the portal.
<script src="https://yobudelivery.com/embed.js"
data-business="Your store"
data-pickup="Your store, 123 Main St, Baltimore, MD"
data-label="Deliver with YOBU" async></script>
Optional: data-target="#my-div" to place the button inside an element.
Support
Questions or a custom integration (POS, Shopify, WooCommerce, pharmacy software)? Call or text (443) 425-8256 or email yobudelivery@gmail.com.