QuikyDeliveries

Developer docs

Integrate deliveries in three calls

Every endpoint speaks JSON. Authenticate with a MagnusID bearer token or the shared pool key for backend-to-backend dispatch. All monetary amounts are BigInt minor units (cents). Distance is miles.

1. Quote

POST /v1/fare/quote
{
  "pickupLat": 40.7128, "pickupLng": -74.0060,
  "dropoffLat": 40.7306, "dropoffLng": -73.9352,
  "tipMinor": 300
}

→ 200 OK
{
  "quote": {
    "distanceMiles": 4.0,
    "totalMinor": "1100",
    "customerTotalMinor": "1400",
    "split": {
      "driverPayoutMinor": "880",
      "quikyBrokeringMinor": "165",
      "quikyInfrastructureMinor": "55"
    },
    "minApplied": false,
    "explanation": "Base $6.00 + distance 4.00mi × per-mile = $11.00 → customer pays $11.00.  Split: driver $8.80 (80%) + Quiky brokering $1.65 (15%) + Quiky infrastructure $0.55 (5%).  Tip $3.00 is 100% to driver (pass-through)."
  }
}

2. Create a delivery

POST /v1/deliveries
Authorization: Bearer <MagnusID token>
Idempotency-Key: <uuid>
{
  "pickup":  { "address": {...}, "lat": 40.7128, "lng": -74.0060 },
  "dropoff": { "address": {...}, "lat": 40.7306, "lng": -73.9352 },
  "customer": { "name": "…", "phone": "…", "email": "…" },
  "description": "Birthday cake",
  "signatureRequired": true,
  "tipMinor": 300
}

→ 201 Created
{
  "delivery": { "id": "…", "status": "created", "trackingSlug": "ab12cd34ef" },
  "job":      { "id": "…", "status": "created" },
  "fare":     { …same shape as quote… },
  "tracking": { "slug": "ab12cd34ef", "url": "/t/ab12cd34ef" },
  "paymentIntent": { "id": "pi_…", "status": "requires_action" }
}

3. Dispatch

POST /v1/jobs/dispatch
{ "jobId": "…" }

→ 200 OK
{ "dispatched": 5, "candidates": [ ... ] }

Public tracking (no auth)

GET /v1/tracking/:slug
→ 200 { "tracking": { "status", "jobStatus", "pickup", "dropoff", "driverLocation", "deliveredAt", "events" } }

Fee audit (Charter §6.4)

GET /api/fee-audit/:deliveryIdOrSlug
→ 200 {
  "audit": {
    "deliveryId": "…",
    "policy": { "version": "charter-v1", "basePerDeliveryMinor": 600, ... },
    "stored": { ...the fee row we charged... },
    "recomputed": { ...the fee engine says now... },
    "drift": { "ok": true, "diffs": [] },
    "explanation": "…"
  }
}

Shared driver pool

QuikyDeliveries owns the shared driver pool used by QuikyEats and QuikyRides. Backend-to-backend callers use x-quiky-pool-key + endpoints under /v1/pool/*. The canonical TypeScript SDK lives at @quikydeliveries/pool-sdk.

import { PoolClient } from "@quikydeliveries/pool-sdk";

const pool = new PoolClient({
  baseUrl: "https://deliveries.quiky.app",
  apiKey: process.env.POOL_SHARED_SECRET!,
});

const candidates = await pool.matchCandidates({
  pickupLat, pickupLng, product: "eats", radiusMiles: 6
});
const job = await pool.createJob({
  product: "eats",
  pickup: { lat, lng, address },
  dropoff: { lat, lng, address },
  totalMinor: "1800",
  driverPayoutMinor: "1440",
});
await pool.dispatchJob(job.id);

Webhooks

QuikyShop, Budlogic, and the Quiky marketplace can push orders into the delivery queue via webhook:

POST /v1/integrations/quikyshop/order-ready
x-webhook-secret: <shared>
{ "sourceOrderId", "senderAccountId", "pickup", "dropoff", "customer", ... }
POST /v1/integrations/budlogic/order-ready
(age-gated 21+ default; signature required; magnusid verification at dropoff)

All prices in USD minor units. All timestamps ISO 8601. All IDs UUIDv4 except tracking slugs (10 hex).