Developers
API referenceBusiness sign in

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:

HTTP
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 and LIVE
TEST (`qd_test_…`)LIVE (`qd_live_…`)
Who can createOwner, Admin or DeveloperOwner or Admin
QuotesReal prices from the same published tariffReal prices
BookingsSimulated QD-TST-… parcels only: no custody, rider, payment or messageReal QD-SHP-… parcels
Tracking, cancel, payment intentsSimulated (QD-TPI-… intents)Real
Labels, manifests, ship runs, webhook endpoints403 (LIVE only)Available
Store ordersInbox records only; never shipped, no webhooksShipped from the inbox or by API
Seeing the other environmentIDs from LIVE answer 404IDs 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.

Scopes
ScopeAllows
locations.readGET /locationsGET /locations/searchGET /locations/{code}
quotes.writePOST /quotesPOST /quotes/options
shipments.writePOST /shipments
wallet.spendSpending confirmed Business wallet funds: needed together with shipments.write or orders.ship for BUSINESS_WALLET bookings, and with shipments.cancel to cancel a wallet-paid parcel.
shipments.readGET /shipmentsGET /shipments/{shipmentId}
shipments.cancelPOST /shipments/{shipmentId}/cancel
tracking.readGET /shipments/{shipmentId}/tracking
labels.readGET /shipments/{shipmentId}/labels/{labelId}.pdf
labels.writePOST /shipments/{shipmentId}/labels
manifests.writePOST /manifests
manifests.readGET /manifests/{manifestId}
payments.writePOST /shipments/{shipmentId}/payment-intents
payments.readGET /payment-intents/{intentId}
services.readGET /services
orders.readGET /ordersGET /orders/{orderId}GET /ship-jobs/{jobId}
orders.writePOST /orders
orders.shipPOST /orders/{orderId}/shipPOST /ship-jobs
webhooks.readGET /webhook-endpoints
webhooks.writePOST /webhook-endpointsPOST /webhook-endpoints/{endpointId}/disablePOST /webhook-endpoints/{endpointId}/test
claims.readGET /claimsGET /claims/{claimId}
claims.writePOST /claimsPOST /claims/{claimId}/evidence
returns.readGET /returnsGET /returns/policyGET /returns/{returnId}
returns.writePOST /returnsPOST /returns/quotePOST /returns/{returnId}/approvePOST /returns/{returnId}/rejectPOST /returns/{returnId}/cancel
analytics.readGET /analytics/summary
checkout.writePOST /checkout/sessionsPOST /checkout/selections/verify

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

Retry rules
ResultWhat to do
Network error or timeoutRetry with the same key and body. The first attempt may have succeeded; the replay tells you.
500, 502, 503, 504, 408Retry with the same key after a short, growing wait (for example 0.5 s, 1 s, 2 s).
429Wait for Retry-After (or the RateLimit header's t=), then retry with the same key.
409Do not retry. The key was used for a different body, the reference is taken, or the parcel changed state.
400, 401, 403, 404, 422Do 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.