Requests, responses and errors
The response envelope, error codes, paging, and how dates, IDs and money are formatted.
Requests
Send JSON bodies with Content-Type: application/json. Every request also carries the two
headers described in Authentication.
Response envelope
Most successful responses wrap the result in one envelope — read your data from data:
{
"status": "…",
"message": "Request was successful",
"data": { }
}message is a human-readable note; build your logic on the HTTP status code and on data,
not on the message text.
A few endpoints return the record directly, without the envelope — for example login (see Authentication) and the item endpoints. Each endpoint's Response Body shows exactly which shape it returns.
Errors
Errors use the HTTP status code plus a short body:
{
"status": "…",
"message": "What went wrong, in plain words"
}| Status | Meaning | Typical cause |
|---|---|---|
400 | Validation or malformed request | A required field is missing or a value has the wrong format |
401 | Missing or invalid token | Log in again — see Authentication |
403 | Feature not enabled for the caller's role | See Permissions |
404 | Record not found in this tenant | Wrong ID, or an ID from another tenant |
409 | Conflict with existing data | A duplicate code, or the record changed state already |
422 | Request understood but cannot be processed | A business rule blocks it, for example a closed period |
Show message to your own users or log it — it says which rule failed.
Paging
List endpoints that can return many records are paged with two query parameters:
| Parameter | Meaning |
|---|---|
page | Page number, starting at 0 |
size | Records per page (each endpoint shows its default) |
A paged data contains the records in content plus paging details:
{
"content": [ ],
"page": 0,
"size": 20,
"totalElements": 134,
"totalPages": 7,
"last": false
}Keep requesting the next page until last is true. Some endpoints nest the paging
details under a page object instead (size, number, totalElements, totalPages) —
each endpoint's response schema shows which shape it uses.
Data formats
| Kind | Format | Example |
|---|---|---|
| Date | YYYY-MM-DD | 2026-10-18 |
| Date and time | ISO 8601 with time zone | 2026-10-18T09:30:00Z |
| IDs | UUID for most records; some record types use whole numbers | 3d07c219-0a88-45be-9cf6-… |
| Money | Decimal number in the merchant's currency | 249.50 |
| Money in minor units | Fields ending in Cents or Minor hold whole minor units | 24950 = 249.50 |
Date-range filters (from, to) take dates in YYYY-MM-DD; each endpoint notes its default range.