Versioning and changelog

v1 grows without breaking you. Every response names its version in Claro-Version.

The promise#

Within v1, nothing you rely on is removed or changed in a breaking way. Every change to the API's contract is checked in CI against the last released one, and a breaking change fails the build.

Breaking means, for example:

• removing an endpoint, a field or a parameter;
• renaming one, or changing its type;
• making an optional parameter required.

What can change without notice#

Additive changes arrive in v1 as they are ready. Build for them:

• New fields. Ignore fields you do not know.
• New values in a string field. Treat an unknown value as the default the reference names for that field. An unknown status is booked, for example.
• New endpoints, error codes and event types. Handle an unknown error code by its type.

The Claro-Version header#

Claro-Version: 2026-11-01

Every response carries it. The value is a date. It changes only when a new version ships, and the changelog says what changed.

Pinning your integration to a version is coming. Each integration will keep the version it was built against until it chooses to move.

The changelog#

Every change to the contract is listed in the changelog, additive ones included.