Skip to content
Courier
فارسی

Partner API

Build delivery into your own system

A small REST API over HTTPS with JSON in and out. Quote a journey, book it, and hear back by webhook as the courier collects and delivers.

QuickstartAPI reference
# 1. What will it cost?curl -u $KEY:$SECRET https://api…/v1/quotes \  -d '{"pickup":  {"latitude": 51.508, "longitude": -0.128},       "dropoff": {"latitude": 51.508, "longitude": -0.076},       "vehicle": "bicycle"}'# 2. Book it. Safe to retry: same key, same job.curl -u $KEY:$SECRET https://api…/v1/jobs \  -H "Idempotency-Key: order-1042" \  -d '{"quote_id": "…", "pickup": {…}, "dropoff": {…}}'→ 201 {"reference": "JOB-7F3K2Q", "status": "searching",        "tracking_url": "https://track…"}

What you build with

  • Quotes

    A fixed price for a journey and a vehicle, broken down line by line, valid until it expires.

    POST /v1/quotes

  • Jobs

    Book against a quote. An Idempotency-Key makes a retry return the same job, never a second one.

    POST /v1/jobs

  • Tracking

    Read a job’s status and stops, the courier’s live position, and a tracking link for your customer.

    GET /v1/jobs/{id}

  • Webhooks

    Signed with HMAC-SHA256 and retried ten times over about an hour and a half, so a short outage loses nothing.

    POST /v1/webhooks

  • Payments

    A card on file, held at booking and captured on delivery. Every charge readable through the API.

    GET /v1/charges

  • Places and routes

    Address search, reverse lookup and the route between two points, for your own booking screens.

    GET /v1/places

A job’s life

Every status change is a webhook, and the same status on GET /v1/jobs/{id}.

  1. pending
  2. searching
  3. courier_assigned
  4. picking_up
  5. in_transit
  6. delivered
  • in_transitreturningreturned

    Could not be handed over, brought back to you

  • cancelled

    Called off before collection — not charged

  • failed

    Nobody took it before the deadline

Webhook events

Each delivery carries the event name, a delivery id to de-duplicate on, and a signature over the timestamp and the body.

# Headers

Courier-Event: job.delivered

Courier-Delivery: 7f3c9e2a-…

Courier-Signature: t=1760090000,v1=5f2c…

Webhook events
  • job.bookedThe job is accepted
  • job.courier_assignedA courier took it
  • job.picked_upCollected from you
  • job.deliveredHanded over, with proof
  • job.returnedBrought back to you
  • job.cancelledCalled off
  • job.failedNo courier took it in time
  • job.status_changedChanged by our operations team
  • payment_method.deadYour card stopped working

Getting a key

  1. 1

    Ask for an account

    We set up your merchant account and its first user.

  2. 2

    Create a sandbox key

    In the portal, under Integration. Keys starting ck_test_ only ever book pretend deliveries.

  3. 3

    Build and test

    Book against the sandbox with test cards and watch the webhooks arrive.

  4. 4

    Go live

    Swap in a ck_live_ key. Nothing else in your code changes.

Start with the quickstart

From a sandbox key to a booked delivery in a few minutes, with curl.

QuickstartTalk to us