Skip to main content

Tracking and events

The truth is one read away​

GET /v1/delivery/jobs/{ref} returns the job as IDM holds it now: status, customer_status, the fee from the frozen snapshot, the pickup and drop-off as words (never coordinates), and the company and rider by name once one is assigned.

GET /v1/delivery/jobs/{ref}/events returns the customer-facing history in sequence order: one entry for each change a customer would see. Internal steps such as offers to riders and relays between riders are left out.

A reference that belongs to another tenant answers exactly like one that does not exist (TENANT_ACCESS_DENIED), so nobody can probe for other tenants' deliveries.

Keeping in step​

Use webhooks to hear about changes as they happen, and the read endpoints to confirm them:

  1. A webhook arrives. Verify it and record its event_id.
  2. If the event matters to a decision (refunds, customer messages, releasing stock), GET the job and act on what it says.
  3. If an event arrives with a sequence lower than one you already processed for that job, it arrived late. Ignore it for state; the later one already reflects it.

If you cannot receive webhooks, poll the job at a modest interval while it is active and stop when it reaches an end state (DELIVERED, CANCELLED or FAILED). Polling counts against your rate limits.

What IDM never tells a tenant​

To protect riders, customers and delivery companies, the API never returns:

  • coordinates of riders or of the pickup and drop-off;
  • how a price was calculated, unless your tenant has detailed pricing visibility;
  • why a particular rider or company was chosen;
  • which other deliveries share a route with yours;
  • anything about other tenants.

Tracking pages for people​

Your customers do not need your integration to follow a delivery. The tracking links on the job's creating answer open IDM's own tracking page. See Track a delivery.