The identity map

Three nouns, and everything else in the API 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: 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, locations get re-addressed, and a mapping keyed on a display name breaks the first time either happens without any error to tell you.

fetchStores also carries the platform's own storefront identifier, so one call joins our identifiers to every platform's. That is the join you want on the boundary of your system; ours is the join you want inside it.

Retired rows are still returned

A brand that has been retired carries a deactivatedAt instant and is still returned by fetchBrands. This is deliberate: a partner reconciling last year's orders still has to resolve the id it recorded then, and an id that stops resolving turns historical data into unattributable rows.

Not every storefront produces orders

A store's mode is worth reading before acting on a row. A reportingOnly storefront will never produce orders through this API however healthy it otherwise looks. New mode values may be added.