Skip to content
ROAD RUNNER

Road Runner API

Book a delivery from your own system, and hear about every change as it happens. Signed requests, idempotent writes, and a webhook for each step.

Dispatch and track deliveries through Road Runner.

This reference is generated from the running code, so it cannot drift from the API you are calling.

A DELIVERY, START TO FINISH 
# 1. What will it cost, and do you deliver there?
POST /v1/quotes
→ { "quote_id": "qt_01J…",
    "fee": { "amount": 500, "currency": "USD" } }

# 2. Book it. Accepted at once, courier found after.
POST /v1/deliveries
→ 202 { "id": "dlv_01J…",
        "status": "pending",
        "tracking_url": "…/t/4A5esdEao2SY" }

# 3. We call you as it moves. No polling.
POST https://yourshop.co.zw/hooks/roadrunner
← { "event": "delivery.delivered",
    "data": { "id": "dlv_01J…" } }

Start here

Quick start

Road Runner issues you a key id (rr_live_…) and a secret (rrsk_…). The secret is sh...

Authentication

Every request carries three headers: Authorization: Bearer rr_live_EXAMPLEKEYID00000...

Idempotency

POST /v1/deliveries requires an Idempotency-Key header. Use your own order reference...

Errors

Every non-2xx response uses one envelope: { "error": { "type": "validation_err...

Quotes

Deliveries

Webhooks

Credentials

Pickup Location

Anything else

The machine-readable document is at /docs/api.json, if you would rather generate a client than read this. If something here does not answer your question, tell us. That is a bug in the documentation.