Versions and changes

#/api/v1 stays compatible

Everything under /api/v1 keeps working as documented. Within v1 we only make changes that existing programs don't notice:

• new endpoints, new optional parameters,
• new fields in answers (ignore fields you don't know),
• new values where a list of values is documented as open (new attributes, new categories),
• new CSV columns, always at the end,
• better messages in errors (go by status and limit, not by message).

Write your client so these don't break it.

#Breaking changes

A change that could break a program (removing or renaming a field or endpoint, changing what a value means) comes only with a new version (/api/v2). Both run side by side for at least 12 months. Endpoints that are going away answer with Deprecation and Sunset headers, and we write to every customer who still calls them.

#The OpenAPI document

The API reference is generated from the API's OpenAPI 3.1 document, /openapi/public-v1.json. It is checked against the code with every change, so it always describes what the API does. Generate a client from it, or import it into Postman, Bruno or Insomnia.

#Changelog

#October 2026

• Webhooks: the change feed pushed to your server, signed, in order (Webhooks).
• Every error links to its explanation (docsUrl).
• The change feed shows changes about 30 seconds after they happen, so a cursor never passes one that was still being written.
• Products across shops (/products), product codes (gtin, mpn, brand) on items, the gtin filter.
• Limits per plan with RateLimit-* and X-Quota-* headers, /plan.