Data freshness
An automated consumer acts on what the API tells it. This page states, per data family, how fresh that data is — so your integration can reason about staleness explicitly instead of discovering it in production.
The contract
Every read that reflects delivery-platform state carries a freshness timestamp. On store status that field is lastPolledAt. It is the moment OneTablet last confirmed the value against the platform — not the moment of your request, and not a promise that the value is current.
Two rules follow, and they are the whole point of the field:
- Check the timestamp before acting. A pause decision taken on hours-old observed state is a foreseeable failure. The field exists so that it never happens silently.
- Prefer webhooks for change detection, reads for reconciliation. The webhook tells you that something changed, with low latency. The read tells you what is true now.
A stale timestamp means "we do not currently know". It does not mean "nothing has changed". Those are different claims and only one of them is safe to automate against.
Freshness by data family
| Data | Source | Freshness |
|---|---|---|
| Orders and order events | OneTablet — we receive them first | Real-time. |
Store intended state (desired.*) | OneTablet's own configured state | Real-time. It is our state; it carries no freshness caveat. |
Store observed state (observed.*) | The delivery platform, swept by us | Hourly sweep, DoorDash / UberEats / GrubHub only. Read lastPolledAt per store — see the caveat below. |
| Discrepancy classification | Reconciliation of the two above | Follows observed-state freshness exactly. A discrepancy is only as fresh as the observation it was derived from. |
Store directory (fetchStores) | OneTablet, with stored platform ids | Real-time for our own fields. platformStoreId and storeUrl are refreshed by the same hourly sweep. |
| Item availability | OneTablet | Real-time for our state; propagation to the platforms is near-real-time. |
| Menus | OneTablet | Real-time for saved state. Published state changes only on an explicit publish. |
| Reports (payouts, transactions, …) | Platform settlement data | T+1 at best. Platforms publish settled data on a daily cycle; same-day figures are provisional. |
| Promotion performance | The delivery platform | T+1 at best, and it varies per platform. |
The observed-state caveat, stated plainly
observed.* — and therefore the discrepancy derived from it — comes from a sweep that runs hourly and today covers DoorDash, UberEats and GrubHub only. Storefronts on any other platform are never swept. Even on the three that are, roughly a third of storefronts carry no reading inside the last 24 hours.
A store that has never been polled at all is absent from fetchStoreStatuses rather than returned with an invented "unknown" state, because an absent row is a gap you will notice and a fabricated one is not.
This is the single most important thing to code around on this API, and it is why lastPolledAt is on every row rather than in a footnote.
Why your polling can never hit a platform's rate limit
Every read that reflects platform state is answered from OneTablet's own refreshed state. Nothing here is proxied per request to a delivery platform. Three consequences you can rely on:
- Your polling cadence is bounded by your limits, never by any platform's.
- One partner's polling can never degrade another's, or ours.
- The price of that isolation is the freshness window — which is exactly why the timestamps above exist, and why this page does.
If your use case needs a tighter observation window on specific stores, raise it with your OneTablet contact. The refresh cadence is a dial, not a constant.