Conventions¶
Formats and types¶
| Item | Rule | Example |
|---|---|---|
| Format | JSON, UTF-8, Content-Type: application/json |
|
| Field names | English snake_case | trade_record_id |
| Code values | Upper case with underscores | DINE_IN |
| Country | ISO 3166-1 alpha-2 | US, JP, TW |
| Currency | ISO 4217; decimal places follow the currency | USD 2, JPY 0, KWD 3 |
| Amount (decimal string) | Decimal number as a string, period as decimal separator, decimal places matching the currency. JSON numbers are rejected. | "1234.50", "-3.00" |
| Quantity (decimal string) | Decimal number as a string (supports weighed items) | "1", "0.5" |
| Tax rate | Decimal fraction as a string (not a percentage) | "0.09" = 9% |
| Time zone | IANA time zone name | America/Los_Angeles |
| Timestamp | ISO 8601 with a UTC offset | 2026-10-14T19:32:05-07:00 |
| Business date | YYYY-MM-DD, store-local, cut at the store's workday_start |
2026-10-14 |
| Language | BCP 47 | en-US, ja-JP, zh-TW |
| Localized text | Object keyed by BCP 47 tag, at least one key | {"en-US":"Fries","zh-TW":"薯條"} |
| UUID | RFC 4122 string | 0b8d6c1e-1111-4a2b-9c3d-222233334444 |
Why amounts are strings
Floating-point numbers cannot represent most decimal amounts exactly. Sending "19.73" as a string guarantees HQ receives exactly what your POS recorded.
Request limits¶
| Item | Limit |
|---|---|
| Records per request | 500 (or your account's max_batch_size, whichever is smaller) |
| Request body size | 5 MB |
| Request rate | 120 requests per minute per partner |
Common request headers¶
| Header | Required | Description |
|---|---|---|
x-functions-key |
Yes (except /health) |
{api_key} — your API key |
Content-Type |
Yes for PUT / POST | application/json |
Common response headers¶
| Header | Description |
|---|---|
X-Request-Id |
Unique ID of the request. Include it when you contact support. |
Retry-After |
Only on 429; seconds to wait before retrying. |
Versioning¶
- The major version is in the path:
/v1. - Adding fields (optional request fields or new response fields) does not change the version. Your client must ignore response fields it does not recognize.
- Removing or changing the meaning of a field creates
/v2, which runs alongside/v1for a transition period.
Personal data¶
Never send any of the following through any endpoint:
- Full card numbers, CVV, cardholder names
- Customer names, phone numbers, email addresses or postal addresses
Card numbers are limited to the last four digits (card_last4).
Members are identified only by member_id, which must be your loyalty system's internal ID. Do not use a phone number, email address or national ID as the member ID. If your loyalty system is keyed by phone number, send an internal sequence number or a salted hash (e.g. SHA-256 with a salt) instead.