Skip to main content

Formats: JSON and XML

Choosing the response format​

Responses come in JSON by default. To get XML:

HowExample
Accept headerAccept: 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.

SituationHTTPcode
Another Content-Type (XML included)415unsupported_media_type
Malformed JSON400invalid_json
Body larger than 256 KB413payload_too_large
Unknown field or invalid value422validation_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​

TypeFormatExample
IdentifiersUUID"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)number6.49
Missing valuesnull"code": null
Field namessnake_casedays_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/false and dates are written as text, in the same format as JSON.
  • Lists become an element with one child per item, in the singular:
ListItem
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>