Start
Authentication and safety
Every request is authenticated with a secret key from your server. Keys have an environment (TEST or LIVE) and explicit scopes, and creating calls carry an idempotency key so you can retry without creating duplicates.
API keys
Send the key as a bearer token on every request:
Authorization: Bearer qd_live_ab12cd34_••••••••••••••••••••••••Keys belong to an API client of one Business. A raw key is shown only when it is created; if you lose it, create a replacement and revoke the old one. Revoking takes effect immediately. A request already in flight may still finish.
TEST and LIVE
| TEST (`qd_test_…`) | LIVE (`qd_live_…`) | |
|---|---|---|
| Who can create | Owner, Admin or Developer | Owner or Admin |
| Quotes | Real prices from the same published tariff | Real prices |
| Bookings | Simulated QD-TST-… parcels only: no custody, rider, payment or message | Real QD-SHP-… parcels |
| Tracking, cancel, payment intents | Simulated (QD-TPI-… intents) | Real |
| Labels, manifests, ship runs, webhook endpoints | 403 (LIVE only) | Available |
| Store orders | Inbox records only; never shipped, no webhooks | Shipped from the inbox or by API |
| Seeing the other environment | IDs from LIVE answer 404 | IDs from TEST answer 404 |
Both use the same base URL. Build and run your test suite with a TEST key, then change only the key.
Scopes
Each key has the scopes ticked when it was created. A call without its scope answers 403. Give each key only what that server needs.
GET /declarations/prohibited-items works with any valid key. GET /openapi.json needs no key.
Idempotency keys and safe retries
Calls that create something require an Idempotency-Key header: quotes, quote options, bookings, cancellations, payment intents, labels, manifests and ship runs.
- The same key with the same body returns the original result (status
200,replayed: true). Nothing new is created. - The same key with a different body answers
409. Never reuse a key for a different request. - Keys are 8–160 characters of
A–Z a–z 0–9 . _ : -(quote options at most 120, ship runs at most 100) and are scoped to your Business and environment. - Store orders need no key: they are idempotent by store and external order ID.
Derive keys from your own records, so a retry after a crash or redeploy sends the same key:
import { idempotencyKey } from '@qoene/delivery';
const key = idempotencyKey('order', order.id, 'book'); // "order:1001:book"
await qoene.shipments.create(booking, { idempotencyKey: key });# Use your order number and the step
-H "Idempotency-Key: order-1001:book"$key = "order-{$order['id']}:book";
$client->post('shipments', ['headers' => ['Idempotency-Key' => $key], 'json' => $booking]);key = f"order-{order['id']}:book"
requests.post(url, headers={**headers, "Idempotency-Key": key}, json=booking, timeout=30)When to retry
| Result | What to do |
|---|---|
| Network error or timeout | Retry with the same key and body. The first attempt may have succeeded; the replay tells you. |
500, 502, 503, 504, 408 | Retry with the same key after a short, growing wait (for example 0.5 s, 1 s, 2 s). |
429 | Wait for Retry-After (or the RateLimit header's t=), then retry with the same key. |
409 | Do not retry. The key was used for a different body, the reference is taken, or the parcel changed state. |
400, 401, 403, 404, 422 | Do not retry unchanged. Fix the request, key or scope. |
The SDK does this for you: it retries network errors, 408, 429 and 5xx only on calls that are safe to repeat, and reuses one idempotency key for all attempts.
Rate limits
Requests are limited per calling server. See Rate limits for the numbers and headers.
HTTPS and data
- Use HTTPS only, and keep certificate verification on in your HTTP client.
- Responses with parcel data are
Cache-Control: private, no-store. Do not cache them in a shared cache. - Receiver names and phone numbers you send are used to deliver the parcel. Webhooks never carry names, phones, addresses or collection codes.