Deliveries

The Delivery API dispatches the Quickli rider fleet for orders, parcels and errands created by your systems. It wraps the same pipeline that powers consumer Quick Send deliveries — riders see identical request cards in their app.

Endpoints

POST/deliveries/estimate
Price a job without dispatching1 token
POST/deliveries
Dispatch a delivery5 tokens
POST/deliveries/batch
Up to 50 per request5 + 2/item
GET/deliveries
List with filters & cursor pagination1 token
GET/deliveries/:id
Full delivery object1 token
GET/deliveries/:id/tracking
Live status + rider + location1 token
POST/deliveries/:id/cancel
Cancel before pickup2 tokens

Lifecycle

Deliveries use the platform-wide order status vocabulary so ops teams, webhooks and the portal all speak the same language:

status-flow
awaiting → accepted → ready →
rider:searching → rider:accepted → rider:at-vendor →
rider:picked-up-order → rider:in-transit → rider:arrived →
rider:dropped-off-order → completed

(any stage before pickup) → canceled

Each transition emits a delivery.status_changed webhook (if subscribed) and triggers recipient SMS/email per your notification preferences.

Pickup sources

  • pickup.locationId — one of your registered locations (preferred; riders get the exact outlet pin & contact).
  • Free-form pickup.lat/lng/address — for arbitrary collection points (customer returns, supplier pickups).

Service area

Both pickup and dropoff must fall inside Quickli-served cities. Validate first with the estimate endpoint (inServiceArea) or GET /locations/:id/coverage. Out-of-area requests fail with GEO_OUT_OF_SERVICE_AREA and are not metered beyond the estimate.

Batch dispatch

For high-volume operations, batch up to 50 deliveries per request. Results are per-item; partial success is normal and idempotency applies to the whole batch envelope.

batch.sh
curl -X POST https://api.quickliapp.com/v1/open/deliveries/batch \
  -H "Authorization: Bearer qk_live_…" -H "Idempotency-Key: batch-4471" \
  -d '{ "deliveries": [ {…}, {…}, …up to 50 ] }'

// → 207 Multi-Status — per-item results
{ "results": [
    { "index": 0, "status": "created", "id": "dlv_…" },
    { "index": 1, "status": "failed", "error": { "code": "GEO_OUT_OF_SERVICE_AREA" } }
]}

Cancellation & refunds

  • Before a rider accepts: free cancellation, delivery fee refunded to your wallet instantly.
  • After acceptance but before pickup: cancellation fee per the standard Quickli cancellation policy applies (shown in the cancel response).
  • After pickup: cannot be canceled via API — contact support through the portal.
  • Platform-side failures (no rider found within the dispatch window) auto-refund in full and emit delivery.failed.

Idempotency is mandatory in spirit

Always send a unique Idempotency-Key (we recommend a UUID per logical delivery, reused across retries). Replays within 24h return the original response and are not re-metered. Without it, a network retry after a timeout could dispatch two riders.