Public beta

Deliveries

Deliveries are the core resource of the Zippex API. Create a delivery to dispatch a driver, then track progress through real-time status updates.

Delivery status flow

Every delivery moves through the following statuses in order. Click a status to see details and its webhook event.

Created

delivery.created

The delivery request has been validated and accepted.

Cancellable

Create a delivery

POST/v1/deliveries

Create a new delivery, either from a quote or with direct addresses.

You can create a delivery in two ways: by providing a quote_id from a previous quote, or by passing the pickup and dropoff addresses directly (a quote will be generated automatically).

Parameters

quote_idstringoptional

ID from a valid, unexpired quote. If provided, pickup_address and dropoff_address are inherited from the quote.

pickup_addressstringoptional

Required if quote_id is not provided. Full pickup street address.

dropoff_addressstringoptional

Required if quote_id is not provided. Full dropoff street address.

pickup_namestringrequired

Contact name at pickup location.

pickup_phonestringrequired

Contact phone at pickup in E.164 format.

dropoff_namestringrequired

Recipient name at dropoff.

dropoff_phonestringrequired

Recipient phone number in E.164 format.

descriptionstringoptional

Package description visible to the driver. Max 500 characters.

package_sizestringoptional

One of small, medium, or large. Ignored if quote_id is provided.

vehiclestringoptional

Preferred vehicle: bike, car, or truck. Ignored if quote_id is provided.

pickup_instructionsstringoptional

Instructions for the driver at pickup. Max 300 characters.

dropoff_instructionsstringoptional

Instructions for the driver at dropoff. Max 300 characters.

metadataobjectoptional

Up to 20 key-value pairs (string keys and values). Use to attach your own order ID, customer ID, etc.

curl -X POST https:"color:#6a9955">//api.zippex.com/v1/deliveries \
  -H "Authorization: Bearer zx_test_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "qt_r4s5t6u7",
    "pickup_name": "Coastal Bites",
    "pickup_phone": "+16045550123",
    "dropoff_name": "Jane Smith",
    "dropoff_phone": "+16045550456",
    "description": "1x Birthday cake — handle with care",
    "dropoff_instructions": "Leave at front desk",
    "metadata": {
      "order_id": "ORD-4521",
      "customer_id": "cust_92834"
    }
  }'

201 Created

{
  "id": "del_m8n9o0p1",
  "status": "created",
  "fee": 1249,
  "currency": "cad",
  "pickup": {
    "address": "350 W Georgia St, Vancouver, BC V6B 6B1",
    "name": "Coastal Bites",
    "phone": "+16045550123",
    "instructions": null
  },
  "dropoff": {
    "address": "2085 Main St, Vancouver, BC V5T 3C3",
    "name": "Jane Smith",
    "phone": "+16045550456",
    "instructions": "Leave at front desk"
  },
  "description": "1x Birthday cake — handle with care",
  "package_size": "medium",
  "vehicle": "car",
  "driver": null,
  "tracking_url": "https://track.zippex.com/del_m8n9o0p1",
  "metadata": {
    "order_id": "ORD-4521",
    "customer_id": "cust_92834"
  },
  "proof_of_delivery": {
    "pickup_photo": false,
    "dropoff_photo": false,
    "photo_skipped": false
  },
  "cancelled_at": null,
  "delivered_at": null,
  "created_at": "2026-03-10T14:01:00Z",
  "updated_at": "2026-03-10T14:01:00Z"
}

Retrieve a delivery

GET/v1/deliveries/{deliveryId}

Retrieve a single delivery by ID.

curl https:"color:#6a9955">//api.zippex.com/v1/deliveries/del_m8n9o0p1 \
  -H "Authorization: Bearer zx_test_abc123def456"

List deliveries

GET/v1/deliveries

List all deliveries with optional filters and pagination.

Returns a paginated list of your deliveries, sorted by creation date (newest first).

Query parameters

statusstringoptional

Filter by status. One of: created, pending, driver_assigned, driver_at_pickup, picked_up, in_transit, delivered, cancelled.

created_afterstringoptional

ISO 8601 timestamp. Only return deliveries created after this time.

created_beforestringoptional

ISO 8601 timestamp. Only return deliveries created before this time.

limitintegeroptional

Number of results per page. Default 20, max 100.

starting_afterstringoptional

Cursor for pagination. Pass the id of the last delivery in the previous page.

curl "https:">//api.zippex.com/v1/deliveries?status=delivered&limit=10&created_after=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer zx_test_abc123def456"

200 OK

{
  "data": [
    {
      "id": "del_m8n9o0p1",
      "status": "delivered",
      "fee": 1249,
      "currency": "cad",
      "pickup": {
        "address": "350 W Georgia St, Vancouver, BC V6B 6B1",
        "name": "Coastal Bites"
      },
      "dropoff": {
        "address": "2085 Main St, Vancouver, BC V5T 3C3",
        "name": "Jane Smith"
      },
      "proof_of_delivery": {
        "pickup_photo": true,
        "dropoff_photo": true,
        "photo_skipped": false
      },
      "created_at": "2026-03-10T14:01:00Z",
      "delivered_at": "2026-03-10T14:45:00Z"
    }
  ],
  "has_more": false
}

Cancel a delivery

POST/v1/deliveries/{deliveryId}/cancel

Cancel an in-progress delivery.

Cancels an in-progress delivery. A cancellation fee may apply if the driver has already been assigned.

reasonstringoptional

Optional cancellation reason. Recorded for your records.

curl -X POST https:"color:#6a9955">//api.zippex.com/v1/deliveries/del_m8n9o0p1/cancel \
  -H "Authorization: Bearer zx_test_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer changed their mind" }'

200 OK

{
  "id": "del_m8n9o0p1",
  "status": "cancelled",
  "cancellation_fee": 250,
  "cancellation_reason": "Customer changed their mind",
  "cancelled_at": "2026-03-10T14:10:00Z",
  "proof_of_delivery": {
    "pickup_photo": false,
    "dropoff_photo": false,
    "photo_skipped": false
  }
}

Cancellation fees

No fee if cancelled before driver assignment. A fee of 250 cents ($2.50 CAD) applies if a driver is already assigned. Deliveries with status picked_up or later cannot be cancelled.

Using metadata

The metadata field accepts up to 20 key-value pairs (both strings, max 500 characters each). Use it to associate deliveries with your internal systems:

Your order ID or invoice number
Customer ID
Internal routing tags

Metadata is returned on every delivery object and included in webhook payloads, so you can use it for reconciliation without additional lookups.

Delivery object

The full delivery object includes these fields:

idstringrequired

Unique delivery ID (del_...).

statusstringrequired

Current delivery status.

feeintegerrequired

Delivery fee in cents.

currencystringrequired

Three-letter currency code (cad).

pickupobjectrequired

Pickup location with address, name, phone, and instructions.

dropoffobjectrequired

Dropoff location with address, name, phone, and instructions.

descriptionstringoptional

Package description.

package_sizestringrequired

One of small, medium, or large.

vehiclestringrequired

Assigned vehicle type.

driverobject | nullrequired

Driver details (name, phone) once assigned. Null before assignment.

tracking_urlstringrequired

Public tracking page URL — safe to share with recipients.

metadataobjectoptional

Your custom key-value pairs.

cancellation_feeinteger | nulloptional

Fee charged on cancellation, in cents.

cancellation_reasonstring | nulloptional

Reason provided when cancelled.

cancelled_atstring | nulloptional

ISO 8601 timestamp of cancellation.

delivered_atstring | nulloptional

ISO 8601 timestamp of delivery completion.

proof_of_deliveryobjectrequired

Proof-of-delivery photo availability. Contains pickup_photo (boolean), dropoff_photo (boolean), and photo_skipped (boolean). Use the /proof endpoint to get actual photo URLs.

pickup_instructionsstring | nulloptional

Driver instructions at pickup, if provided.

dropoff_instructionsstring | nulloptional

Driver instructions at dropoff, if provided.

timelinearrayrequired

Array of {status, timestamp} objects showing the delivery lifecycle.

created_atstringrequired

ISO 8601 creation timestamp.

updated_atstringrequired

ISO 8601 last-update timestamp.

Proof of delivery

GET/v1/deliveries/{deliveryId}/proof

Get short-lived signed URLs for proof-of-delivery photos.

Drivers capture photos at pickup and dropoff as proof of delivery. For security, photo URLs are not included in standard delivery responses. Instead, check the proof_of_delivery object for availability, then call this endpoint to get temporary signed URLs.

Signed URLs

Photo URLs expire after 1 hour. Request new URLs each time you need to display photos. Never cache or store these URLs permanently — they are designed to be short-lived for security.

curl https:"color:#6a9955">//api.zippex.com/v1/deliveries/del_m8n9o0p1/proof \
  -H "Authorization: Bearer zx_test_abc123def456"

200 OK

{
  "pickup_photo_url": "https://storage.googleapis.com/zippex-71294.appspot.com/pickupPhotos/abc123.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600&X-Goog-Signature=...",
  "dropoff_photo_url": "https://storage.googleapis.com/zippex-71294.appspot.com/dropOffPhotos/abc123.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600&X-Goog-Signature=...",
  "expires_at": "2026-03-10T15:45:00Z"
}

No photos available?

If neither photo exists for a delivery, this endpoint returns a 404. Check proof_of_delivery.pickup_photo or proof_of_delivery.dropoff_photo before calling this endpoint.

Next step

Continue to Tracking if you need live ETA data, or Webhooks if your backend should react to delivery status changes.