# Merchant API versions

:::warning
Versioning is required in your API calls. If you don't provide a version header, you will receive an error response.

On endpoints where the version header is optional, 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.

While we aim to provide a long support window, older API versions will eventually be deprecated and decommissioned. Refer to our [Deprecation policy](/docs/guides/merchant/reference/versioning/deprecation-policy) for details on this process.
:::

### 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 and API versions marked as **Deprecated** are scheduled to be decommissioned and will no longer be available after a specific period.

We provide a support window of at least **six months** from the date an endpoint is deprecated. We recommend migrating your integration to the latest version during this time to avoid any disruption of service.

For complete details on the API lifecycle, version statuses, and notification timelines, please see our dedicated [Deprecation policy](/docs/guides/merchant/reference/versioning/deprecation-policy).

## 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:

```http
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