{"title":"Versioning","category":"default","creationDate":1779533780,"content":"<p>We constantly improve our products and add new functionalities on our platform. Usually these improvements and functionalities result in new product versions.<\/p>\n<div class=\"additional-info-block output-inline\">\n<h5 class=\"article__heading additional-info-block__title\">API Diff Tool<\/h5><div class=\"additional-info-block__body\"><p>Use our  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/api-diff-tool\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">API Diff Tool<\/a> to compare any two versions of an API.<\/p><\/div><\/div>\n\n<p>On this page, we describe the versioning of our APIs and server-side libraries.<\/p>\n<h2>APIs<\/h2>\n<p>When we introduce changes to our APIs, we follow best practices to have the least disruption on existing integrations. For example, for our REST APIs, we follow the <a href=\"https:\/\/www.thoughtworks.com\/radar\/techniques\/api-expand-contract\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">API expand-contract<\/a> pattern to add new elements without changing the version.<\/p>\n<p>While we strive to reduce impact to existing integrations, we sometimes have to introduce changes that are not compatible with existing API versions. Doing so enables us to keep our APIs consistent and to improve the quality and developer experience.<\/p>\n<p>When we introduce a breaking or incompatible change, we release a new API version to accommodate the change. The definition of a breaking change depends on the <a href=\"#new-vs-classic\">type of API<\/a>.<\/p>\n<h3 id=\"current-version\">Checking the API version<\/h3>\n<p>Most integrations use multiple Adyen APIs (see our <a href=\"https:\/\/docs.adyen.com\/api-explorer\/\" class=\"codeLabel?classes=codeLabel external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">API Explorer<\/a>. Each API has a different version. Depending on how you are making the API calls, you can check the versions of the APIs that you are using from:<\/p>\n<ul>\n<li>Direct calls from your server: you can see the API version in the URLs that you use to reach the Adyen platform.<\/li>\n<li>Server-side libraries: when a <a href=\"\/development-resources\/versioning#server-side-libraries\">server-side library version<\/a> is released, the API version is included in the release notes. For example, see <a href=\"https:\/\/github.com\/Adyen\/adyen-java-api-library\/releases\/tag\/17.2.0\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Adyen Java API library 17.2.0<\/a>.<\/li>\n<\/ul>\n<p>Each API URL contains a version suffix starting with either \"v\" or \"V\" character followed by a whole number to indicate the API version. We increment the number for every version, but <a href=\"#new-version-without-changes\">we may skip numbers<\/a> when needed.<\/p>\n<p>Here are some examples of different API versions:<\/p>\n<pre><code class=\"language-bash\">https:\/\/checkout-test.adyen.com\/v68\/payments                             \/\/ version 68\nhttps:\/\/cal-test.adyen.com\/cal\/services\/Account\/v6\/createAccountHolder   \/\/ version 6\nhttps:\/\/balanceplatform-api-test.adyen.com\/bcl\/v1\/balanceAccounts        \/\/ version 1<\/code><\/pre>\n<p>To check if you are using the latest API version, refer to the version in our <a href=\"https:\/\/docs.adyen.com\/api-explorer\/\" class=\"codeLabel?classes=codeLabel\/ external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">API Explorer<\/a>.<\/p>\n<h3 id=\"new-vs-classic\">New vs classic APIs<\/h3>\n<p>We categorize our APIs into two types: <em>new<\/em> or <em>classic<\/em> APIs. The type determines whether a change is compatible with an existing API version. For example, in new Adyen APIs, adding an optional field to a response body is a non-breaking change, while in classic APIs this change is considered breaking and therefore requires a new API version.<\/p>\n<p>The following are classic APIs:<\/p>\n<ul>\n<li><a href=\"https:\/\/docs.adyen.com\/api-explorer\/#\/Payment\/latest\/overview\" class=\"codeLabel?classes=codeLabel\/ external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Payment<\/a><\/li>\n<li>\n <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Recurring\/latest\/overview\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Recurring<\/a>\n<\/li>\n<li>\n <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Payout\/latest\/overview\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Payout<\/a>\n<\/li>\n<li><a href=\"https:\/\/docs.adyen.com\/api-explorer\/#\/BinLookup\/latest\/overview\" class=\"codeLabel?classes=codeLabel\/ external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">BinLookup<\/a><\/li>\n<\/ul>\n<p>All other APIs that are not in the list above are new APIs, such as  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Checkout\/latest\/overview\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Checkout<\/a> and <a href=\"https:\/\/docs.adyen.com\/api-explorer\/#\/balanceplatform\/latest\/overview\" class=\"codeLabel?classes=codeLabel\/ external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Balance Platform<\/a>.<\/p>\n<h3 id=\"non-breaking-changes\">Non-breaking changes<\/h3>\n<p>A <em>non-breaking<\/em> or <em>backward-compatible<\/em> change is an API change that allows your integration to continue using the API without any additional changes on your side. When we introduce new functionalities and changes to our APIs, we do our best to implement them in a backward-compatible way. We implement non-breaking changes in all versions of an API, so that you benefit from it without having to upgrade your API version.<\/p>\n<p>We consider the following changes as non-breaking, depending on the <a href=\"#new-vs-classic\">API type<\/a>.<\/p>\n<div class=\"sticky-table-container\">\n    \n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Non-breaking changes<\/th>\n<th style=\"text-align: center;\">New APIs<\/th>\n<th style=\"text-align: center;\">Classic APIs<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">Adding a new endpoint<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Adding an optional field to a request body<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Adding any field to a response body<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><a href=\"#breaking-changes\">Breaking change<\/a><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Adding an optional header to a request<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Adding a header to a response<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Changing the case of a header name<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Changing the value of a header<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Changing a field from required to optional in a request body<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Changing a field from optional to required in a response body<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Changing the text of an error message in a response<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Add a new HTTP status code for the response<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Deprecating a request or response field (for documentation)<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n<\/div>\n\n<h3 id=\"breaking-changes\">Breaking changes<\/h3>\n<p>A <em>breaking change<\/em> is an API change that makes your current integration incompatible with the API. To avoid disrupting existing integrations, we introduce breaking changes in a new API version. You can continue to use existing API versions until you are ready to upgrade to the new version.<\/p>\n<p>We consider the following changes as breaking, depending on the <a href=\"#new-vs-classic\">API type<\/a>.<\/p>\n<div class=\"sticky-table-container\">\n    \n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Breaking change<\/th>\n<th style=\"text-align: center;\">New&nbsp;APIs<\/th>\n<th style=\"text-align: center;\">Classic&nbsp;APIs<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">Adding a required field to a request body<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Adding any field to a response body<\/td>\n<td style=\"text-align: center;\"><a href=\"#non-breaking-changes\">Non-breaking change<\/a><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Adding a required header to a request<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Removing an existing endpoint<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Removing a field from a request body<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Removing a field from a response body<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Removing a header from a request<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Removing a header from a response<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Changing the HTTP status code of a response<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Changing error codes for an existing error<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Changing a field from optional to required in a request body<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Changing a field from required to optional in a response body<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Renaming a field in a request or response<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Changing the type of a field in a request or response<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Changing the behavior in a way that requires API consumers to change their integration for it to work properly. <br><br> For example, if an API was ignoring some errors and now starts returning a validation error, the change is a breaking change.<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n<\/div>\n\n<h3 id=\"new-version-without-changes\">New API version without changes<\/h3>\n<p>In some cases, we may introduce a new API version without visible changes to API consumers. We do so to improve stability and consistency of our APIs, or to implement some groundwork for bigger changes in the future.<\/p>\n<p>For the same reason, we sometimes skip numbers in a versioning of specific APIs.<\/p>\n<h3 id=\"upgrade-api\">Upgrading to a new API version<\/h3>\n<p>In general, we recommend upgrading to new API versions whenever possible. Keeping your integration up-to-date is crucial so you can take advantage of recent developments and improvements in our platform. However, if you decide stay in your current version, you can continue to do so. We maintain older versions of our APIs that you can continue to use until you are ready to upgrade.<\/p>\n<p>To prepare for an API upgrade, refer to the release notes to find out about changes. For example, <a href=\"\/online-payments\/release-notes?integration_type=api\">Checkout API<\/a>.<\/p>\n<h2>Server-side libraries<\/h2>\n<p>Our <a href=\"\/development-resources\/libraries\">server-side API libraries<\/a> provide you with a convenient way to integrate without the need to directly connect to our APIs from your server-side code. Each library provides classes and methods that lets you use multiple Adyen APIs without needing to know the API versions. Instead, you need to consider the library version, which you specify when you include a library into your project.<\/p>\n<h3>Versioning<\/h3>\n<p>Adyen server-side API libraries use <a href=\"https:\/\/semver.org\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">semantic versioning<\/a>, which is based on the <em>MAJOR.FEATURE.MINOR<\/em> format:<\/p>\n<ul>\n<li>A <em>MAJOR<\/em> version release includes breaking changes to older usages of endpoints, such as changes in declarations and parameters.<\/li>\n<li>A <em>FEATURE<\/em> version release includes new, non-breaking features.<\/li>\n<li>A <em>MINOR<\/em> version release includes bug fixes or small non-breaking changes to endpoints.<\/li>\n<\/ul>\n<h3 id=\"upgrade-library\">Upgrading to a new version of a server-side library<\/h3>\n<p>We recommend that you upgrade to the latest version to benefit from new API releases and bug fixes. Check the latest releases from our <a href=\"https:\/\/github.com\/Adyen\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">GitHub repository<\/a>.<\/p>\n<h2 id=\"see-also\">See also<\/h2>\n<div class=\"see-also-links output-inline\" id=\"see-also\">\n<ul><li><a href=\"https:\/\/docs.adyen.com\/api-explorer\/?classes=codeLabel?classes=codeLabel\/\"\n                        target=\"_blank\"\n                         class=\"external\">\n                    API Explorer\n                <\/a><\/li><li><a href=\"https:\/\/github.com\/Adyen\"\n                        target=\"_blank\"\n                         class=\"external\">\n                    Server-side libraries on GitHub\n                <\/a><\/li><\/ul><\/div>\n","url":"https:\/\/docs.adyen.com\/development-resources\/versioning","articleFields":{"description":"Find out how Adyen applies versioning to APIs and server-side libraries.","feedback_component":true,"id":"34120911","type":"page","_expandable":{"operations":""},"status":"current","last_edit_on":"18-01-2022 16:03"},"algolia":{"url":"https:\/\/docs.adyen.com\/development-resources\/versioning","title":"Versioning","content":"We constantly improve our products and add new functionalities on our platform. Usually these improvements and functionalities result in new product versions.\n\nAPI Diff ToolUse our  API Diff Tool to compare any two versions of an API.\n\nOn this page, we describe the versioning of our APIs and server-side libraries.\nAPIs\nWhen we introduce changes to our APIs, we follow best practices to have the least disruption on existing integrations. For example, for our REST APIs, we follow the API expand-contract pattern to add new elements without changing the version.\nWhile we strive to reduce impact to existing integrations, we sometimes have to introduce changes that are not compatible with existing API versions. Doing so enables us to keep our APIs consistent and to improve the quality and developer experience.\nWhen we introduce a breaking or incompatible change, we release a new API version to accommodate the change. The definition of a breaking change depends on the type of API.\nChecking the API version\nMost integrations use multiple Adyen APIs (see our API Explorer. Each API has a different version. Depending on how you are making the API calls, you can check the versions of the APIs that you are using from:\n\nDirect calls from your server: you can see the API version in the URLs that you use to reach the Adyen platform.\nServer-side libraries: when a server-side library version is released, the API version is included in the release notes. For example, see Adyen Java API library 17.2.0.\n\nEach API URL contains a version suffix starting with either \"v\" or \"V\" character followed by a whole number to indicate the API version. We increment the number for every version, but we may skip numbers when needed.\nHere are some examples of different API versions:\nhttps:\/\/checkout-test.adyen.com\/v68\/payments                             \/\/ version 68\nhttps:\/\/cal-test.adyen.com\/cal\/services\/Account\/v6\/createAccountHolder   \/\/ version 6\nhttps:\/\/balanceplatform-api-test.adyen.com\/bcl\/v1\/balanceAccounts        \/\/ version 1\nTo check if you are using the latest API version, refer to the version in our API Explorer.\nNew vs classic APIs\nWe categorize our APIs into two types: new or classic APIs. The type determines whether a change is compatible with an existing API version. For example, in new Adyen APIs, adding an optional field to a response body is a non-breaking change, while in classic APIs this change is considered breaking and therefore requires a new API version.\nThe following are classic APIs:\n\nPayment\n\n Recurring\n\n\n Payout\n\nBinLookup\n\nAll other APIs that are not in the list above are new APIs, such as  Checkout and Balance Platform.\nNon-breaking changes\nA non-breaking or backward-compatible change is an API change that allows your integration to continue using the API without any additional changes on your side. When we introduce new functionalities and changes to our APIs, we do our best to implement them in a backward-compatible way. We implement non-breaking changes in all versions of an API, so that you benefit from it without having to upgrade your API version.\nWe consider the following changes as non-breaking, depending on the API type.\n\n    \n\n\n\nNon-breaking changes\nNew APIs\nClassic APIs\n\n\n\n\nAdding a new endpoint\n\n\n\n\nAdding an optional field to a request body\n\n\n\n\nAdding any field to a response body\n\nBreaking change\n\n\nAdding an optional header to a request\n\n\n\n\nAdding a header to a response\n\n\n\n\nChanging the case of a header name\n\n\n\n\nChanging the value of a header\n\n\n\n\nChanging a field from required to optional in a request body\n\n\n\n\nChanging a field from optional to required in a response body\n\n\n\n\nChanging the text of an error message in a response\n\n\n\n\nAdd a new HTTP status code for the response\n\n\n\n\nDeprecating a request or response field (for documentation)\n\n\n\n\n\n\n\n\nBreaking changes\nA breaking change is an API change that makes your current integration incompatible with the API. To avoid disrupting existing integrations, we introduce breaking changes in a new API version. You can continue to use existing API versions until you are ready to upgrade to the new version.\nWe consider the following changes as breaking, depending on the API type.\n\n    \n\n\n\nBreaking change\nNew&nbsp;APIs\nClassic&nbsp;APIs\n\n\n\n\nAdding a required field to a request body\n\n\n\n\nAdding any field to a response body\nNon-breaking change\n\n\n\nAdding a required header to a request\n\n\n\n\nRemoving an existing endpoint\n\n\n\n\nRemoving a field from a request body\n\n\n\n\nRemoving a field from a response body\n\n\n\n\nRemoving a header from a request\n\n\n\n\nRemoving a header from a response\n\n\n\n\nChanging the HTTP status code of a response\n\n\n\n\nChanging error codes for an existing error\n\n\n\n\nChanging a field from optional to required in a request body\n\n\n\n\nChanging a field from required to optional in a response body\n\n\n\n\nRenaming a field in a request or response\n\n\n\n\nChanging the type of a field in a request or response\n\n\n\n\nChanging the behavior in a way that requires API consumers to change their integration for it to work properly.  For example, if an API was ignoring some errors and now starts returning a validation error, the change is a breaking change.\n\n\n\n\n\n\n\n\nNew API version without changes\nIn some cases, we may introduce a new API version without visible changes to API consumers. We do so to improve stability and consistency of our APIs, or to implement some groundwork for bigger changes in the future.\nFor the same reason, we sometimes skip numbers in a versioning of specific APIs.\nUpgrading to a new API version\nIn general, we recommend upgrading to new API versions whenever possible. Keeping your integration up-to-date is crucial so you can take advantage of recent developments and improvements in our platform. However, if you decide stay in your current version, you can continue to do so. We maintain older versions of our APIs that you can continue to use until you are ready to upgrade.\nTo prepare for an API upgrade, refer to the release notes to find out about changes. For example, Checkout API.\nServer-side libraries\nOur server-side API libraries provide you with a convenient way to integrate without the need to directly connect to our APIs from your server-side code. Each library provides classes and methods that lets you use multiple Adyen APIs without needing to know the API versions. Instead, you need to consider the library version, which you specify when you include a library into your project.\nVersioning\nAdyen server-side API libraries use semantic versioning, which is based on the MAJOR.FEATURE.MINOR format:\n\nA MAJOR version release includes breaking changes to older usages of endpoints, such as changes in declarations and parameters.\nA FEATURE version release includes new, non-breaking features.\nA MINOR version release includes bug fixes or small non-breaking changes to endpoints.\n\nUpgrading to a new version of a server-side library\nWe recommend that you upgrade to the latest version to benefit from new API releases and bug fixes. Check the latest releases from our GitHub repository.\nSee also\n\n\n                    API Explorer\n                \n                    Server-side libraries on GitHub\n                \n","type":"page","locale":"en","boost":18,"hierarchy":{"lvl0":"Home","lvl1":"Development resources","lvl2":"Versioning"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/development-resources","lvl2":"\/development-resources\/versioning"},"levels":3,"category":"Development Resources","category_color":"green","tags":["Versioning"]}}