Public beta

Tracking

The tracking endpoint provides real-time driver location, ETA, and status for an active delivery. Use it to build live tracking experiences for your customers.

Get delivery tracking

GET/v1/deliveries/{deliveryId}/tracking

Get real-time tracking data including driver location and ETA.

Returns the current tracking state for a delivery. Driver location is only available once status reaches driver_assigned.

deliveryIdstringrequired

The delivery ID (path parameter).

curl https:"color:#6a9955">//api.zippex.com/v1/deliveries/del_m8n9o0p1/tracking \
  -H "Authorization: Bearer zx_test_abc123def456"
200 OK
{
  "delivery_id": "del_m8n9o0p1",
  "status": "in_transit",
  "driver": {
    "name": "Alex M.",
    "phone": "+16045550100",
    "location": {
      "lat": 49.2827,
      "lng": -123.1207
    },
    "heading": 45
  },
  "eta_minutes": 12,
  "pickup": {
    "address": "350 W Georgia St, Vancouver, BC V6B 6B1",
    "arrived_at": "2026-03-10T14:15:00Z",
    "picked_up_at": "2026-03-10T14:18:00Z"
  },
  "dropoff": {
    "address": "2085 Main St, Vancouver, BC V5T 3C3",
    "delivered_at": null
  },
  "tracking_url": "https://track.zippex.com/del_m8n9o0p1",
  "updated_at": "2026-03-10T14:22:00Z"
}

Response fields

delivery_idstringrequired

The delivery ID.

statusstringrequired

Current delivery status.

driverobject | nullrequired

Driver info including name, phone, location (lat/lng), and heading (degrees). Null before assignment.

eta_minutesinteger | nullrequired

Estimated minutes to next milestone (pickup or dropoff). Null if no ETA is available.

pickupobjectrequired

Pickup details with timestamps for arrived_at and picked_up_at.

dropoffobjectrequired

Dropoff details with delivered_at timestamp.

tracking_urlstringrequired

Public tracking page URL safe to share with recipients.

updated_atstringrequired

ISO 8601 timestamp of the last tracking update.

Polling recommendations

If you are polling the tracking endpoint (rather than using webhooks), follow these guidelines:

  • Poll every 10 to 30 seconds while the delivery is active. Faster polling does not yield more frequent location updates.
  • Stop polling once the status is delivered or cancelled.
  • Use webhooks for status changes and polling only for location updates to minimize API calls.
  • Check the updated_at timestamp to avoid processing stale data.
async function pollTracking(deliveryId, apiKey) {
  const POLL_INTERVAL_MS = 15_000; "color:#6a9955">// 15 seconds

  const poll = async () => {
    const res = await fetch(
      `https:"color:#6a9955">//api.zippex.com/v1/deliveries/${deliveryId}/tracking`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );

    const tracking = await res.json();

    console.log(`Status: ${tracking.status}, ETA: ${tracking.eta_minutes} min`);

    if (tracking.driver?.location) {
      console.log(`Driver at: ${tracking.driver.location.lat}, ${tracking.driver.location.lng}`);
    }

    "color:#6a9955">// Stop polling on terminal status
    if (tracking.status === 'delivered' || tracking.status === 'cancelled') {
      console.log('Delivery complete — stopping poll.');
      return;
    }

    setTimeout(poll, POLL_INTERVAL_MS);
  };

  poll();
}

Prefer webhooks for status transitions and use this endpoint for user-facing live tracking, map rendering, or ETA refreshes.

Sandbox tracking behavior

In test mode (zx_test_ key), tracking data is simulated:

  • The driver location moves along a realistic path between pickup and dropoff.
  • ETA decreases over time to simulate real delivery progress.
  • Status auto-advances on a timer: created (10s) then driver_assigned (15s) then picked_up (20s) then in_transit (30s) then delivered.
  • Driver name is always "Test Driver" and phone is +10000000000.

See the Sandbox page for full details on test mode behavior.

Public tracking URL

Every delivery includes a tracking_url that points to a Zippex-hosted tracking page. This URL is safe to share directly with your customers -- no API key or authentication is needed.

https:"color:#6a9955">//track.zippex.com/del_m8n9o0p1

Next step

If you also need backend automation, continue to Webhooks.