Booking a delivery: worked example

This page walks through a complete booking, end to end: get a quote, choose a rate, book the delivery, then track it. Every request below is copy-pasteable — replace YOUR_API_KEY and the addresses.

Step 1 — Get a quote

Ask Quiver what's available for this collection point, delivery address and parcel. You'll get back the rates you can book.

curl -X POST https://api.quiver.london/task/quotes \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryType": "NEXT_DAY",
    "collection": {
      "address": {
        "line1": "143 Newport Street",
        "city": "London",
        "postcode": "SE11 6AQ",
        "country": "United Kingdom"
      }
    },
    "delivery": {
      "address": {
        "line1": "22 Rivington Street",
        "city": "London",
        "postcode": "EC2A 3DY",
        "country": "United Kingdom"
      }
    },
    "customer": {
      "firstName": "Alex",
      "lastName": "Doe",
      "email": "[email protected]",
      "phoneNumber": "+447700900123"
    },
    "order": {
      "merchantOrderId": "1001",
      "merchantOrderName": "#1001"
    }
  }'

customer and order are required. A response looks like:

{
  "eligibility": "FULL",
  "rates": [
    {
      "rateCode": "QUIV_DEL_ND",
      "name": "Next Day",
      "description": "Delivered tomorrow",
      "price": { "amount": 599, "currency": "GBP" },
      "window": {
        "from": "2026-08-04T09:00:00Z",
        "to": "2026-08-04T18:00:00Z"
      },
      "co2Savings": 0.42
    }
  ]
}

Reading the response

eligibility is FULL when every requested service is available, or PARTIAL when only some are. If a particular rate can't be offered, that rate carries an error explaining why.
price.amount is in minor units — 599 means £5.99.
window is the delivery window you're being offered.
An empty rates array means Quiver can't serve this route — fall back to another carrier.

Quotes go stale after roughly 2 minutes. Request one immediately before booking rather than caching it.

Step 2 — Book the delivery

Send the same details plus the rateCode you chose.

curl -X POST https://api.quiver.london/task/deliveries \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryType": "NEXT_DAY",
    "rateCode": "QUIV_DEL_ND",
    "collection": {
      "address": {
        "line1": "143 Newport Street",
        "city": "London",
        "postcode": "SE11 6AQ",
        "country": "United Kingdom"
      }
    },
    "delivery": {
      "address": {
        "line1": "22 Rivington Street",
        "city": "London",
        "postcode": "EC2A 3DY",
        "country": "United Kingdom"
      }
    },
    "customer": {
      "firstName": "Alex",
      "lastName": "Doe",
      "email": "[email protected]",
      "phoneNumber": "+447700900123"
    },
    "order": {
      "merchantOrderId": "1001",
      "merchantOrderName": "#1001"
    }
  }'

{
  "taskId": 228760,
  "createdAt": "2026-08-03T14:34:35.389746Z",
  "taskType": "DELIVERY",
  "status": { "taskId": 228760, "value": "NOT_STARTED" },
  "deliveryType": "NEXT_DAY",
  "trackingId": "AIW7QY",
  "trackingUrl": "https://track.quiver.london/AIW7QY",
  "rateCode": "QUIV_DEL_ND"
}

Store two things: taskId (to look the delivery up later) and trackingId / trackingUrl (to show your customer).

merchantOrderId is your own order reference, and Quiver de-duplicates on it. Send the same value on any retry and you can never create two deliveries for one order. See Errors and retries.

Step 3 — Track it

Two options — prefer webhooks.

Webhooks (recommended). Subscribe in Settings → Integrations at app.quiver.co.uk and we'll POST to your endpoint on every status change. Respond 200 to acknowledge.

Polling. Look up a delivery by your own order reference:

curl "https://api.quiver.london/task/deliveries?merchantOrderId=1001" \
  -H "x-api-key: YOUR_API_KEY"

This is also how you recover after a timeout — if you never saw the booking response, query by merchantOrderId to find out whether it went through.

Booking a return

Returns use the same shape, posted to /task/returns — collection is the customer's address and delivery is yours.

Next steps

How a delivery works — statuses, windows and what happens operationally
Errors and retries — handling failures safely