How often tracking data refreshes, and how to schedule around it

The short answer

There is no fixed sync time. We do not run a 9am or 10am batch. Each shipment re-syncs on a rolling gap measured from its own last sync:

• At most every 12 hours for a shipment with a long way to go.
• Every 4 hours while it is arriving — from 48 hours before its arrival date until 7 days after it.

The shorter window exists because that is when a carrier actually revises a date. A box three weeks out rarely changes; one due on Tuesday can move to Saturday at any hour, and waiting half a day to find that out is half a day of showing you a date that has already passed.

After 7 days overdue it goes back to the 12-hour gap. At that point the line has stopped publishing anything about the box, and asking more often costs money and returns the same row.

What actually triggers a sync

• Somebody opens the shipment. Viewing a shipment refreshes it, on every plan including free. Attention is the best signal there is that a number matters.
• The background sweep. On paid plans, shipments are re-synced even when nobody is looking. This is what a paid plan buys — not refreshing at all, but refreshing while you sleep.
• You ask. The refresh control on a shipment, and the tracking endpoints on the API, both re-sync on the spot.

All three share the same gap. A manual refresh is not extra on top of the automatic one — it is two per rolling day in total, or six while the shipment is arriving, however they are triggered.

If you are scheduling a job around it

The mistake to avoid is picking a time. Because the gap runs from each shipment's own last sync rather than from a wall clock, shipments drift relative to each other and there is no window that is reliably "after the refresh".

Ask for what changed instead of guessing when it changed:

1. Pull the delta. GET /api/v1/shipments?updated_since=<ISO timestamp of your last run> returns only the shipments whose tracking data has moved since then. This is the primitive built for exactly this job — it is far cheaper than re-reading your whole book, and it cannot miss a change by landing between syncs.
2. Read the timestamp. Every row carries last_synced_at, and next_refresh_eligible_at says when that row can next change — already adjusted for which of the two gaps applies to it.
3. Force the few that matter. For shipments that are both stale and important, call the tracking endpoint for those references. They re-sync on the spot if they are outside their gap.

Reading the timestamp rather than assuming a schedule is also the only approach that stays correct if the cadence ever changes.

Why a timestamp can look old and not be stale

Ocean carriers publish in batches, not continuously. A status that last synced eight hours ago is often not us being behind — it is the most recent thing the line has said about that box. The timestamp tells you when we last asked; if nothing changed, asking again produces the same row with a newer timestamp and no new information.

If a shipment is clearly moving and we appear to be more than a day behind on it, that is worth reporting — send us the reference and we will look at the feed.

Not sure what applies to your account?

Ask the assistant in the help drawer — it can read your plan and tell you whether the background sweep is on for you, when a specific reference last synced, and when it is next eligible.