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 12-hour minimum gap measured from its own last sync, which works out to at most twice a day per shipment.

That ceiling is not us being cautious with your data — it is what the carrier feeds themselves will give us. Asking a line for the same container more often than that returns the same answer, so a tighter cycle would spend money and change nothing on your screen.

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 12-hour gap. A manual refresh is not extra on top of the automatic one — it is two per rolling day in total, 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. Decide what "current enough" means for your process; for most inventory reporting a figure under 12 hours old is the same figure you would get by asking again.
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 the 12-hour 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 usually 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.