API versions

caution

We highly recommend using versioning in your API calls. If you don't provide a version header on the operations where it's required, you will receive an error response.

On endpoints using header versioning, if the version header is not required, the API will default to the earliest version.

About API versioning​

The Merchant API is versioned, meaning that in different API versions specific operations behave differently: consuming or returning different data, accepting different path parameters or enum values, etc.

The API version name is based on the date when the respective version was released. For example, the API version 2023-09-01 was released on Fri, 1 Sep 2023.

note

The Merchant API is transitioning to header versioning, with some endpoints already updated, while others still using path versioning.

If the Revolut-Api-Version header is present in the API specification, it indicates that versioning is available for that endpoint and is required if specified.

Using versioning will be mandatory for future releases. Integrations using older versions stay working and past versions won't be decommissioned.

Breaking changes​

When breaking changes are deployed, a new API version will be released. Breaking changes are changes that could break an integration, these changes include:

  • removing an entire operation
  • removing or renaming a parameter
  • removing or renaming a response field
  • adding a new required parameter
  • making a previously optional parameter required
  • changing the type of a parameter or response field
  • removing enum values
  • adding a new validation rule to an existing parameter
  • changing authentication or authorization requirements

Non-breaking changes​

Non-breaking (additive) changes will be available in all supported API versions. Non-breaking changes are changes that should not break an integration, these changes include:

  • adding an operation
  • adding an optional parameter
  • making a previously required parameter optional
  • adding an optional request header
  • adding a response field
  • adding a response header
  • adding enum values

Deprecated endpoints​

Endpoints labeled as deprecated will continue to function until further notice. They won't be decommissioned, ensuring that existing integrations remain operational.

However, it is highly recommended to update to newer versions to take advantage of the latest features, improvements, and support. Keeping integrations up to date with the latest versions will ensure compatibility and performance as the API evolves.

Request header versioning​

The Merchant API uses request header versioning. Where it is required you need to use the Revolut-Api-Version header parameter to specify an API version. Each request, where it is indicated in the API specification, must contain a version header in the following format:

'Revolut-Api-Version: 2023-09-01'

If the Revolut-Api-Version header is optional, the endpoint will default to the earliest version if the header is not provided.

The Merchant API will return a 400 error response in the following cases when versioning is required:

  • Using an invalid Revolut-Api-Version header, invalid values include:
    • non-existent API versions,
    • API versions removed from the list of supported versions
  • Not providing the Revolut-Api-Version header where it's required

Change log​

Version 2024-09-01​

Version 2024-05-01​

Version 2023-09-01​

Deprecated endpoints​

Was this page helpful?