API conventions
These rules hold for every operation on this API.
One path per operation, everything in the body
Every operation is a POST to a fixed path with a typed JSON request object. There are no path parameters and no query strings, so a request is fully described by its URL and its body.
No version segment
The base path carries no /v1. Changes are additive: new optional fields and new operations are added, so a working client keeps working.
Money is an integer in the currency's minor unit
1250 is $12.50. The API never sends a decimal amount. Send whole numbers only.
Times are ISO-8601 in UTC
Fields that carry an instant are typed string<date-time> in the reference. To show a store's local time, convert with the store's IANA timezone from fetchStores.
Ignore fields you do not recognise
Optional fields may be added to request and response objects at any time. A new field always has a defined meaning when it is absent, so an existing client keeps working.
Every call has a transaction id
A response from an operation, successful or not, carries the x-mealco-tx-id response header. It identifies that one call.
- Log it with every call. Store it beside your own record of the request.
- Quote it to support. With a transaction id we can find the record of that call.
- It is also in error bodies. An error body carries the same value as
txId.
You may send your own. Set x-mealco-tx-id on a request and that value is used as the id for the call and returned on the response. Send a value that is unique per request and at most 200 printable characters. A longer value, or one that contains control characters, is not returned: that response carries no x-mealco-tx-id header. If you send nothing, an id is generated.
The transaction id is a label only. It grants no access and is never used for authorization. Do not put personal data in it, and do not rely on its format.
Two responses are produced before a call reaches an operation and carry no id: the 400 for a request whose body is not valid JSON, and a 429 from the rate limiter. See Getting Started → Errors and retries.