API conventions
Adapted from the Management API's
docs/concepts/01-api-conventions.md(ONE-2099) — most of this platform's conventions hold identically here. Two differences from the twin: this API has no money fields (it provisions locations and brands, not orders), so that bullet is dropped here; and it has no cursor pagination (none of the three operations returns a paged collection), so that bullet is dropped too. If you change a bullet that exists on both pages, check the twin.
Three rules hold everywhere on this API. Learn them once and every operation reads the same.
One path per operation, everything in the body
Every operation is a POST to a fixed, verb-first path with a typed JSON request object. No path parameters, no query strings. A request is therefore fully described by its URL and its body, which is what makes it trivial to log, replay and diff.
No version segment
The base path carries no /v1. Evolution here is additive — new optional fields and new operations, never removals or narrowing — so there is no cutover a version segment would ever mark. Ignore fields you do not recognise and your client survives every release.
Unknown fields are your problem to ignore, not ours to withhold
We add optional fields to existing request and response objects at any time. A new field always has a defined meaning when absent, so an older client is never wrong — only less informed.
Times, where a field carries one, are ISO-8601 in UTC
A store's local time is a rendering decision, and the API does not make it for you — resolve it from the location's IANA timezone. Fields carrying an instant are typed string<date-time> in the reference.