Formats: JSON and XML
Choosing the response format
Responses come in JSON by default. To get XML:
| How | Example |
|---|---|
Accept header | Accept: application/xml (or text/xml) |
format parameter | ?format=xml |
The format parameter takes priority over the header, which helps with tools that cannot change headers. Accept: application/json, */* or no Accept at all result in JSON. Any other format gets a 406 error (not_acceptable).
Errors also come in the chosen format.
Request bodies
The body of POST and PATCH must be UTF-8 JSON, with Content-Type: application/json.
| Situation | HTTP | code |
|---|---|---|
Another Content-Type (XML included) | 415 | unsupported_media_type |
| Malformed JSON | 400 | invalid_json |
| Body larger than 256 KB | 413 | payload_too_large |
| Unknown field or invalid value | 422 | validation_error |
Unknown fields are refused, not ignored. That way a typo, such as day_to_be_next instead of days_to_be_next, shows up right away.
Data formats
| Type | Format | Example |
|---|---|---|
| Identifiers | UUID | "6b7e1f0a-…" |
Expiry dates (exp_date) | YYYY-MM-DD, no time zone | "2026-12-31" |
Date and time (created_at, updated_at, deleted_at) | ISO 8601 in UTC | "2026-11-05T17:40:00.123Z" |
Numbers (amount, price, cost_price) | number | 6.49 |
| Missing values | null | "code": null |
| Field names | snake_case | days_to_be_next |
The expiry date never shifts because of time zones: what you send is what comes back.
In date-time filters (updated_since, since), always include the time zone, for example 2026-11-06T13:00:00Z or 2026-11-06T10:00:00-03:00.
JSON example
{
"data": {
"id": "6b7e1f0a-3c2d-4e5f-8a9b-0c1d2e3f4a5b",
"name": "Whole milk 1L",
"code": "7891000100103",
"days_to_be_next": 15,
"brand_id": null,
"category_id": "a1c2d3e4-…",
"store_id": null,
"has_image": false,
"created_at": "2026-11-05T17:40:00.000Z",
"updated_at": "2026-11-05T17:40:00.000Z"
}
}
The same example in XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
<data>
<id>6b7e1f0a-3c2d-4e5f-8a9b-0c1d2e3f4a5b</id>
<name>Whole milk 1L</name>
<code>7891000100103</code>
<days_to_be_next>15</days_to_be_next>
<brand_id nil="true"/>
<category_id>a1c2d3e4-…</category_id>
<store_id nil="true"/>
<has_image>false</has_image>
<created_at>2026-11-05T17:40:00.000Z</created_at>
<updated_at>2026-11-05T17:40:00.000Z</updated_at>
</data>
</response>
XML rules
- The document starts with
<?xml version="1.0" encoding="UTF-8"?>and has a single root element,<response>. - Elements have the same names as the JSON fields.
- Null values become an empty element with
nil="true". - Numbers,
true/falseand dates are written as text, in the same format as JSON. - Lists become an element with one child per item, in the singular:
| List | Item |
|---|---|
data of /v1/products | <product> |
data of /v1/batches and /v1/products/{id}/batches | <batch> |
data of /v1/categories, /v1/brands, /v1/stores | <category>, <brand>, <store> |
data of /v1/deletions | <deletion> |
batches (with include=batches) | <batch> |
scopes | <scope> |
details (errors) | <detail> |
List example:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<data>
<batch>
<id>…</id>
<exp_date>2026-12-31</exp_date>
…
</batch>
</data>
<pagination>
<limit>50</limit>
<has_more>false</has_more>
<next_cursor nil="true"/>
</pagination>
</response>