Versioning and deprecation

Versions#

The API version is in the path: /api/v1. This is the only version today.

We make changes to v1 without a new version when they are backwards compatible:

new endpoints
new optional request fields
new fields in responses (so ignore fields you do not recognise)
new event types (so ignore events you do not handle)
new error code values for existing statuses (so keep a default branch)
looser limits

We ship a new version (/api/v2) for anything that could break a correct integration:

removing or renaming a field, endpoint or event
changing a field's type or unit
making an optional field required
changing the meaning of a status code or state

Deprecation policy#

When we deprecate something:

It is announced in the changelog and by email to the owners of API keys that use it.
Deprecated endpoints answer with a Deprecation: true header and, once a date is set, a Sunset header carrying the removal date.
It keeps working for at least six months after the announcement. The exception is a security fix that cannot wait: we will say so plainly in the changelog and tell affected keys directly.
A migration guide is published with the announcement.
After the sunset date it returns 410 Gone.

Security-driven changes#

Some changes tighten behaviour to protect your money and data, for example API payouts going only to your saved settlement account. These are listed in the changelog under Security and marked when they can affect an existing integration.

Current deprecations#

None. Where the current API has a known inconsistency (for example major units on some fields and minor on others) it is documented rather than silently changed, and will be addressed in a future version.

Staying informed#

Read the changelog, and keep an owner email on your business account that someone reads.