API conventions
Six 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 makes it simple to log, replay and diff.
No version segment
The base path carries no /v1. Changes are additive: new optional fields and new operations are added. Ignore fields you do not recognise and your client keeps working across releases.
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.
Times are ISO-8601 in UTC
A store's local time is a rendering decision that the API leaves to you. Resolve it from the location's IANA timezone. Fields carrying an instant are typed string<date-time> in the reference.
Ignore fields you do not recognise
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 stays correct without it.
Every call has a transaction id
A response from an operation, whether a 200 or a 400, 401 or 500, carries the x-mealco-tx-id response header. It is the identifier we use to follow one call end to end.
Log it against every call you make. Store it beside your own record of the request, so that every call you send can be traced later.
Quote it to support. A status code and a time of day are not enough to find a call. With the transaction id, we can find the complete record of that call.
It also appears as txId in any error body, so you hold it whether you log headers or bodies. When both are present they are the same value.
You may send your own. Set x-mealco-tx-id on a request and we adopt it: it is what we record against the call and what comes back on the response, so your correlation id and ours are the same string. Send a value that is unique per request, because a reused value makes several calls indistinguishable. Keep it to 200 characters or fewer of ordinary printable text. Anything longer or containing control characters is not returned: that response carries no x-mealco-tx-id header. If you send nothing, we generate one for you.
It is a label only. It carries no authorization and no access of any kind. Sending someone else's transaction id grants nothing, and the id is never used to decide what a request may see. Do not put customer names, email addresses, card data or any other personal information in it, and do not read meaning into the format: it is opaque, and it may change shape without notice.
Two responses are produced before a call reaches an operation and carry no id. A request whose body is not valid JSON is rejected before it is processed, so that response carries neither the header nor a txId in the body. A rate-limit rejection carries no id either. See Getting Started → Errors and retries.