The identity map
The API has three core nouns. Everything else is addressed by one of their ids.
- Location: a physical kitchen. It has an address and an IANA
timezone, and it carries the brands operating out of it. - Brand: the name guests order from. One brand runs at many locations.
- Store: a single storefront, which is one brand, at one location, on one delivery platform. This is the row that has a platform-side identifier, and the row orders belong to.
A store is therefore the intersection of the other two plus a platform. That is why there are three directory reads rather than one: fetchLocations, fetchBrands and fetchStores.
Join on ids, never on names
Every store carries its location.id and brand.id. The name strings are for rendering only. Brands get renamed and locations get re-addressed, and a mapping keyed on a display name then breaks without an error.
fetchStores also carries the platform's own storefront identifier, so one call joins our identifiers to every platform's. Use the platform identifier at the boundary of your system and the Sous Chef ids inside it.
Retired rows are still returned
A brand that has been retired carries a deactivatedAt instant and is still returned by fetchBrands, so that an id you recorded with past orders still resolves when you reconcile historical data.
Not every storefront produces orders
Read a store's mode before acting on a row. A reportingOnly storefront does not produce orders through this API, whatever its other fields show. New mode values may be added.