Skip to main content

Show customers where their delivery is

"When will my delivery arrive?" is the question your customer service hears most. The answer is in Alrik the moment a planner puts the order on a tour — which vehicle it is on, how far the driver has got, and a live estimate of when they will reach each stop.

This guide shows how to surface that, whether in a customer-service screen in your ERP or on a tracking page for your customers.

What you will build

  • A view of what is on the road today for a branch.
  • For any order: which tour it is on, who is driving, and its estimated arrival.
  • Confirmation, with proof, once it has been delivered.

Before you begin, you need an API key with permission to read orders, and the origin_reference of each branch you want to track — see Locations.

How tracking fits together​

MomentWhere the answer comes from
Not yet plannedOrder drafts — the order is there, not yet converted
Planned or on the roadActive tours — the tour, driver, vehicle and live estimates
DeliveredA callback, or the order's delivery timestamps

1. Fetch today's tours for a branch​

Active tours returns everything planned or under way for one location: each tour, its driver and vehicle, and its stops in order. By default you get today's tours. Pass an earlier date to pick up tours from that day that are still running.

Fetch it on a short timer for the branches you care about, rather than once per customer enquiry — one paginated request per branch covers every order on the road.

2. Find the customer's order​

Each stop carries your order number, so look for the dropoff stop whose order number matches. That stop is the one to show your customer: its address, its position in the tour, and its estimated arrival.

Tours can also contain breaks. A break is a stop with no order on it — skip it.

3. Show the arrival estimate​

The stop's estimated_arrival_at is Alrik's current estimate of when the driver will get there, and it moves as the tour runs. It is the field to show a waiting customer.

Convert the time before you show it

Arrival estimates and everything else that records when something happened are in UTC, written without an offset. Planned dates and times are in local time. Convert before comparing the two, and before showing an arrival time to a customer.

For more than an estimate, the stop also records when the driver set off for it, arrived and finished — enough to show "on the way", "arrived" and "delivered".

4. Handle carrier deliveries​

Not every tour is run by your own fleet. Check handled_by on the tour first:

  • Your own fleet — the tour names the driver and vehicle.
  • An external carrier — the tour names the carrier instead, and records when the delivery was sent to them and whether they have accepted it.

Only handled_by is guaranteed on every tour. A newly planned tour can carry very little else, so show what is there and leave the rest blank.

5. Confirm delivery​

The cleanest way to learn an order has been delivered is to let Alrik tell you. Callback events fire when an order is fulfilled and when proof of delivery is uploaded, with a link to the signature or photo.

Without callbacks, get an order shows its progress as a series of timestamps; the delivery is complete once fulfilled_at is set.

Keep your API key on your server

If you build a tracking page for customers, call Alrik from your own backend and pass on only what the page needs. Your key can do everything your integration is allowed to do — never put it in browser or app code.