API conventions

Five 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.

Money is an integer in the currency's minor unit

1250 is $12.50. A decimal amount cannot survive a round trip through every language's default number type, so the API never emits one. All Phase 0 order amounts are USD; a currency field will be added additively before non-USD markets onboard.

Times 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.

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.