1. API versioning at Numeral

Numeral uses versioning to introduce breaking changes without impacting live customers. Breaking changes include changes such as:

An attribute being renamed
An attribute being removed
An attribute format being changed
A new logic being implemented for an existing feature

API versions are numbered using their release date (e.g., 2023-04-12). API versions are maintained for a minimum of 12 months after a new API version is released.

New customers and new API keys for existing customers are linked to the latest API version. Existing customers and API keys are automatically migrated to the latest API version 90 days after it has been released. They can force a specific version of the API by setting it in their API requests.

New features and improvements to existing features are only available in the latest API version.

The public documentation refers to the latest API version.

2. API versions

Version	Changelog	Default version date after
`2023-04-12`	Changelog API version 2023-04-12	May 24, 2023

3. Setting the API version

To use a specific version of the API, use the Numeral-Api-Version HTTP header of your API requests as follows:

curl --request GET \
     --url 'https://sandbox.numeral.io/v1/payment_orders?limit=25' \
     --header 'accept: application/json' \
     --header 'x-api-key: 279413050bb4455e9ae4dfb0bdf210fd' \
     --header 'numeral-api-version: 2023-04-12'