Versioning

The Raïs API is versioned by date. The current version is 2026-10-26.

Where the version appears

• Every response, errors included, carries it in the Rais-Version header:

HTTP/1.1 200 OK
Rais-Version: 2026-10-26
Rais-Request-Id: req_8f3a1c9d2b7e4a60

• Every event carries it as api_version, which tells you what shape its payload has.
• The OpenAPI document states it as info.version.

Breaking and non-breaking changes

Changes that could break an integration will only ever come with a new version. They are announced in the changelog before they apply.

These changes are not breaking, and can happen within a version at any time:

• a new endpoint, a new optional request parameter, a new response field;
• a new value of an enumeration, for example a new event type or a new payment status;
• a new error code, or a new header;
• a change to the wording of an error message;
• longer ids, and a different order of the keys of an object.

These are breaking, and need a new version: removing or renaming a field, changing its type or its meaning, making an optional parameter required, and removing an endpoint or an event.

Write tolerant code

• Ignore response fields you do not know.
• Do not fail on an event type, a status or an error code you do not know: handle the unknown value with a sensible default, and answer unknown events with a 2xx status.
• Branch on error code, never on message.
• Do not depend on the order of the keys of a JSON object.

Upgrading

When a new version is released, the changelog says what changes, why, and from when. Read it before you upgrade, test with sandbox keys, and watch the Rais-Version header of your responses in your logs.