Public beta

Deliveries

Deliveries are the core resource of the Zippex API. Create one from a quote to dispatch a driver, then poll status updates or subscribe to webhooks for real-time progress.

Test mode is fully simulated

Requests authenticated with a zx_test_ key never dispatch a real driver. The endpoint persists a delivery record and returns a synthetic timeline so you can build against the real response shape end to end.

Delivery status flow

Every live delivery moves through these statuses in order. Test deliveries auto-advance through the simulated timeline returned on creation.

Created

delivery.created

The delivery request has been validated and accepted.

Cancellable

Create a delivery

POST/v1/deliveries

Create a delivery from a quote and dispatch a driver.

Always create a quote first via POST /v1/quotes and pass the returned quote_id here. The quote provides authoritative pricing and route data; this endpoint records the customer details and creates the delivery.

Live deliveries require a paid checkout

In live mode you must collect payment first: create a checkout via POST /v1/checkouts, have the customer pay, then pass the resulting checkout_id here. Without it the request returns 400 missing_checkout. Test-mode (zx_test_) deliveries are simulated and need no checkout.

Parameters

quote_idstringrequired

ID returned from POST /v1/quotes. Must be unused. Quotes expire after 15 minutes; expired quotes are re-priced and rejected if drift exceeds 10%.

checkout_idstringrequired

Required in live mode. The paid checkout from POST /v1/checkouts for the same quote. Funds the delivery so your net share and Zippex’s service fee settle automatically. Not required in test mode.

customer.namestringrequired

Recipient name shown to the driver.

customer.phonestringrequired

Recipient phone number. Stored as E.164.

customer.emailstringoptional

Recipient email for notifications.

dropoff_notesstringoptional

Instructions for the driver at dropoff. Max 500 characters.

external_referencestringoptional

Your internal order ID. Returned on the delivery and in webhooks for reconciliation. Max 120 characters.

categorystringoptional

Delivery category. When creating from a quote, this is inherited from the quote's category, passing a different value returns 400 (category_quote_mismatch). When creating without a quote, defaults to "standard". Restricted values ("alcohol", "cannabis") gate the delivery to drivers who have uploaded and been approved for the corresponding BC certification, see "Restricted categories" below.

Restricted categories require driver certifications

When you set category to "alcohol" or "cannabis", the dispatch engine only notifies drivers whose corresponding certification is on file and approved by Zippex:

alcohol → driver must have Serving It Right on file (BC liquor service certification).
cannabis → driver must have Selling It Right on file (BC cannabis retail certification).

Restricted deliveries may take longer to match in areas with few certified drivers. Pickup must originate from a venue licensed to sell the corresponding product.

curl -X POST https:"color:#6a9955">//developer.zippex.app/api/v1/deliveries \
  -H "Authorization: Bearer zx_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "qt_dr_4f8a2b1c0d3e6f",
    "customer": {
      "name": "Jane Smith",
      "phone": "+16045550456",
      "email": "jane@example.com"
    },
    "dropoff_notes": "Leave at front desk",
    "external_reference": "ORD-4521",
    "category": "alcohol"
  }'

Response (test mode)

201 Created

{
  "id": "del_dr_3a8c92e0b7d124",
  "mode": "test",
  "status": "simulated",
  "quote_id": "qt_dr_4f8a2b1c0d3e6f",
  "price": 1249,
  "currency": "cad",
  "external_reference": "ORD-4521",
  "category": "alcohol",
  "tracking_url": "https://zippex.app/track/del_dr_3a8c92e0b7d124",
  "simulated_timeline": [
    {
      "status": "created",
      "at": "2026-05-07T14:00:00.000Z"
    },
    {
      "status": "driver_assigned",
      "at": "2026-05-07T14:01:00.000Z"
    },
    {
      "status": "picked_up",
      "at": "2026-05-07T14:08:00.000Z"
    },
    {
      "status": "delivered",
      "at": "2026-05-07T14:24:00.000Z"
    }
  ],
  "created_at": "2026-05-07T14:00:00.000Z"
}

Response (live mode)

The live response echoes the payment breakdown from the funded checkout. See Payments for how the amounts settle.

201 Created

{
  "id": "del_dr_3a8c92e0b7d124",
  "mode": "live",
  "status": "created",
  "order_id": "jZc1f8AbcDef",
  "quote_id": "qt_dr_4f8a2b1c0d3e6f",
  "price": 1249,
  "currency": "cad",
  "external_reference": "ORD-4521",
  "category": "alcohol",
  "payment": {
    "status": "paid",
    "checkout_id": "chk_dr_abc123def456",
    "payment_intent_id": "pi_xxx",
    "amount_charged": 5749,
    "items_subtotal": 4500,
    "service_fee": 450,
    "developer_net": 4050
  },
  "tracking_url": "https://zippex.app/track/del_dr_3a8c92e0b7d124",
  "created_at": "2026-05-07T14:00:00.000Z"
}

Retrieve a delivery

GET/v1/deliveries/{deliveryId}

Retrieve a single delivery and its current status.

For live deliveries, the response includes the latest status from the driver-app dispatch system and driver coordinates once assigned. Test deliveries return the persisted record without driver info.

curl https:"color:#6a9955">//developer.zippex.app/api/v1/deliveries/del_dr_3a8c92e0b7d124 \
  -H "Authorization: Bearer zx_test_your_api_key_here"

200 OK

{
  "id": "del_dr_3a8c92e0b7d124",
  "mode": "live",
  "status": "in_transit",
  "simulated": false,
  "quote_id": "qt_dr_4f8a2b1c0d3e6f",
  "order_id": "jZc1f8AbcDef",
  "price": 1249,
  "currency": "cad",
  "external_reference": "ORD-4521",
  "category": "alcohol",
  "pickup": {
    "address": "350 W Georgia St",
    "city": "Vancouver",
    "state": "BC",
    "postalCode": "V6B 6B1",
    "country": "CA",
    "lat": 49.282,
    "lng": -123.118
  },
  "dropoff": {
    "address": "2085 Main St",
    "city": "Vancouver",
    "state": "BC",
    "postalCode": "V5T 3C3",
    "country": "CA",
    "lat": 49.2611,
    "lng": -123.1006
  },
  "customer": {
    "name": "Jane Smith",
    "email": null
  },
  "driver": {
    "name": "Sam Driver",
    "phone": "+16045559999",
    "vehicle": "car",
    "lat": 49.271,
    "lng": -123.11
  },
  "tracking_url": "https://zippex.app/track/del_dr_3a8c92e0b7d124",
  "created_at": "2026-05-07T14:00:00.000Z",
  "updated_at": "2026-05-07T14:14:00.000Z"
}

List deliveries

GET/v1/deliveries

List your deliveries scoped to the API key's mode.

Returns deliveries created with the calling key’s mode (test keys see test deliveries, live keys see live). Sorted by creation date, newest first.

Query parameters

limitintegeroptional

Page size. Default 20, max 100.

cursorstringoptional

Pass the next_cursor value from the previous response to fetch the next page.

statusstringoptional

Filter by status (e.g., created, simulated, delivered).

curl "https:">//developer.zippex.app/api/v1/deliveries?limit=20" \
  -H "Authorization: Bearer zx_test_your_api_key_here"

200 OK

{
  "data": [
    {
      "id": "del_dr_3a8c92e0b7d124",
      "mode": "test",
      "status": "simulated",
      "quote_id": "qt_dr_4f8a2b1c0d3e6f",
      "order_id": null,
      "price": 1249,
      "currency": "cad",
      "external_reference": "ORD-4521",
      "category": "alcohol",
      "created_at": "2026-05-07T14:00:00.000Z",
      "updated_at": "2026-05-07T14:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Roadmap

The following endpoints are not yet available on direct API keys and are planned for upcoming releases:

POST /v1/deliveries/{id}/cancel, explicit cancellation with policy-based fee
GET /v1/deliveries/{id}/proof, signed URLs for proof-of-delivery photos
Outgoing delivery webhooks, subscribe instead of polling

Until cancellation lands, contact support@zippex.com if you need to cancel a live delivery.

Next step

Continue to Tracking for the polling pattern and live ETA, or Webhooks for event subscription guidance.