API docs
Sous Chef Management API
Request access

Data freshness

An automated consumer acts on what the API tells it. This page states, for each data family, how fresh that data is, so that your integration can handle staleness explicitly.

The contract

A read that Sous Chef answers from stored delivery-platform state carries a freshness timestamp. On store status that field is lastPolledAt. It is the moment Sous Chef last confirmed the value against the platform. It is not the moment of your request, and it does not mean that the value is current.

Two rules follow:

  1. Check the timestamp before acting. A decision taken on an old observation can be wrong. The timestamp lets you detect that case.
  2. 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". These are different claims, and only the first is safe to automate against.

Freshness by data family

DataSourceFreshness
Orders and order eventsSous Chef (we receive them first)Real-time.
Store intended state (desired.*)Sous Chef's own configured stateReal-time. It is our state; it carries no freshness caveat.
Store observed state (observed.*)The delivery platform, swept by usHourly sweep on DoorDash, Uber Eats and Grubhub. Read lastPolledAt per store. See the caveat below.
Discrepancy classificationReconciliation of the two aboveFollows observed-state freshness exactly. A discrepancy is only as fresh as the observation it was derived from.
Store directory (fetchStores)Sous Chef, with stored platform idsReal-time for our own fields. platformStoreId and storeUrl are recorded when the sweep first reads a store.
Item availabilitySous ChefReal-time for our state; propagation to the platforms is near-real-time.
MenusSous ChefReal-time for saved state. Published state changes only on an explicit publish.
Reports (payouts, transactions, …)Platform settlement dataSame day to four days behind, by report type. Read dataLag from fetchReportCoverage.
Uber Eats promotionsUber Eats, read on each requestLive. fetchUberEatsPromotions and fetchUberEatsPromotion call Uber Eats when you call them.

The observed-state caveat

observed.*, and therefore the discrepancy derived from it, comes from a sweep that runs hourly. Observation covers DoorDash, Uber Eats and Grubhub. A storefront on one of them may have no recent reading, and lastPolledAt shows the age of each observation.

A store that has never been polled is absent from fetchStoreStatuses. It is not returned with a placeholder "unknown" state.

Code for these cases: read lastPolledAt on every row before you act on it.

Why polling does not reach a platform's rate limit

Store, status, menu and order reads are answered from Sous Chef's own refreshed state. They are not proxied per request to a delivery platform. Three consequences follow:

  • Your polling cadence is bounded by your limits, never by any platform's.
  • One partner's polling does not degrade another's.
  • The cost of that isolation is the freshness window, which is why the timestamps above exist.

The two Uber Eats promotion reads are the exception. They call Uber Eats on each request, so read promotions when you need them rather than on a tight loop.

If your use case needs a tighter observation window on specific stores, contact support@yoursouschef.com.