How tracking updates work

Atlas does three things the second a carrier scan happens.

1. We poll

Every 15 minutes, a background job (/api/cron/poll-tracking) asks each carrier for the latest scan on every shipment that is purchased or in_transit.

2. We store the full history

Every scan becomes a row in tracking_events. You see it under the shipment's Activity timeline. The most recent scan is also denormalized onto the shipment row as tracking_status.

3. We push downstream

On every meaningful transition we:

• Update the shipment row (your dashboard updates live, no refresh needed)
• Drop a notification in your bell
• POST a signed webhook to every partner endpoint subscribed to that event type
• Email the customer (if enabled)
• Text the customer (if opted in)

What if a scan is missing?

Carrier feeds occasionally lag. We re-poll after 15 minutes. If a shipment hasn't updated in 24 hours we surface it in Insights → Stuck shipments.