{"_id":"5cbf3a5b2f8a0c01c208b3e9","project":"555fbba928249c1900618a82","initVersion":{"_id":"5c880f30807b06006266135b","version":"2.19"},"user":{"_id":"5c4b4e5b39a20b00dc863b8a","username":"","name":"Dominique Saulet"},"__v":0,"hidden":false,"createdAt":"2019-04-23T16:16:27.922Z","fullscreen":false,"htmlmode":false,"html":"","body":"The purpose of this page is to provide information pertaining to Recurly's support of the v2 API and its associated client libraries.  The API Release, Deprecation, and Retirement Schedule, found [below](#api-version-release-deprecation-and-retirement-sch), is of particular importance.\n\nIf you have any questions, please [reach out to our team](https://support.recurly.com/) at any time.\n[block:api-header]\n{\n  \"title\": \"Recurly API v2 Client Libraries\"\n}\n[/block]\nRecurly provides client libraries in several programming languages, making it is possible to access the v2 API without making direct calls to the HTTP endpoints.  Recurly supports official client libraries in Ruby, Python, PHP, and .NET.  \n\nUnofficial, community supported client libraries are available in Java, Node.js, Go, and Elixir. See our [https://dev.recurly.com/docs/client-libraries](https://dev.recurly.com/docs/client-libraries) for more information.  \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Please note that all client library related information in this document pertains specifically to the official client libraries.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"API Releases and Backward-Compatibility\"\n}\n[/block]\nRecurly provides new API releases continuously in order to deliver new features, to improve performance, to fix bugs, and to provide enhanced security.  While our aim is to always provide these updates in a backward-compatible fashion, breaking changes are sometimes unavoidable. As such, we release new versions of our API from time to time in order to avoid disrupting existing customer integrations.\n\nAlthough we guarantee that new versions of the API will be supported and remain available for at least two years from release, it is important to maintain a regular upgrade schedule for your integration, migrating to the latest version of our API as often as possible. This will ensure that you benefit from new functionality, improved performance, and security updates as they become available.\n[block:api-header]\n{\n  \"title\": \"API Version Release, Deprecation, and Retirement Schedule\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"API versions are deprecated two years after the date that the subsequent version is released ( rounded to the nearest month) and they are retired six months after the deprecation date.\"\n}\n[/block]\n\n* **Deprecation means that Recurly will no longer support, provide bug fixes, or patch security issues for a given API version**\n\n* **Retirement means that a given API version will no longer function.**\n\n*Example:\nIf API version v2.3 is released on March 25th, 2015 and API version v2.4 is released August 7th, 2015, then v2.3 would be deprecated on September 1st, 2017, two years after the release of v2.4. Retirement of v2.3 would occur on Feb. 1st, 2018, six months after the deprecation date*\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The following schedule provides release dates for currently supported versions of our API along with deprecation and retirement dates based on the policy noted above.\\n\\nClient library versions follow the same release, deprecation, and retirement schedule as their associated API version.  In order to determine which version of the API your client library version is using, please refer to the [upgrade guides below](#client-library-upgrade-guides)\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"9-3\": \"May, 2021\",\n    \"9-0\": \"2.15\",\n    \"h-0\": \"API Version\",\n    \"h-1\": \"Release Date\",\n    \"h-2\": \"Deprecation Date\",\n    \"h-3\": \"Retirement Date\",\n    \"0-0\": \"2.6 (and lower)\",\n    \"1-0\": \"2.7\",\n    \"2-0\": \"2.8\",\n    \"3-0\": \"2.9\",\n    \"4-0\": \"2.10\",\n    \"5-0\": \"2.11\",\n    \"6-0\": \"2.12\",\n    \"7-0\": \"2.13\",\n    \"8-0\": \"2.14\",\n    \"10-0\": \"2.16\",\n    \"11-0\": \"2.17\",\n    \"12-0\": \"2.18\",\n    \"13-0\": \"2.19\",\n    \"0-1\": \"May 2017 (and earlier)\",\n    \"1-1\": \"June 2017\",\n    \"2-1\": \"Oct. 2017\",\n    \"3-1\": \"Nov. 2017\",\n    \"4-1\": \"Jan. 2018\",\n    \"5-1\": \"Apr. 2018\",\n    \"6-1\": \"May 2018\",\n    \"7-1\": \"June 2018\",\n    \"8-1\": \"Aug. 2018\",\n    \"9-1\": \"Sept. 2018\",\n    \"10-1\": \"Oct. 2018\",\n    \"11-1\": \"Dec. 2018\",\n    \"12-1\": \"Feb. 2019\",\n    \"13-1\": \"March 2019\",\n    \"0-2\": \"July 1, 2019\",\n    \"1-2\": \"Nov. 1, 2019\",\n    \"2-2\": \"Dec. 1, 2019\",\n    \"3-2\": \"Feb. 1, 2020\",\n    \"4-2\": \"May 1, 2020\",\n    \"5-2\": \"June 1, 2020\",\n    \"6-2\": \"July 1, 2020\",\n    \"7-2\": \"Sept. 1, 2020\",\n    \"8-2\": \"Oct. 1, 2020\",\n    \"9-2\": \"Nov. 1, 2020\",\n    \"10-2\": \"Jan. 1, 2021\",\n    \"11-2\": \"March 1, 2021\",\n    \"12-2\": \"April 1, 2021\",\n    \"13-2\": \"TBD\",\n    \"13-3\": \"TBD\",\n    \"0-3\": \"Feb 1, 2020\",\n    \"1-3\": \"May 1, 2020\",\n    \"2-3\": \"June 1, 2020\",\n    \"3-3\": \"Aug. 1, 2020\",\n    \"4-3\": \"Nov. 1, 2020\",\n    \"5-3\": \"Dec. 1, 2020\",\n    \"6-3\": \"Jan 1, 2021\",\n    \"7-3\": \"March 1, 2021\",\n    \"8-3\": \"April 1, 2021\",\n    \"10-3\": \"July 1, 2021\",\n    \"11-3\": \"Sept. 1, 2021\",\n    \"12-3\": \"Oct. 1, 2021\"\n  },\n  \"cols\": 4,\n  \"rows\": 14\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"An unversioned call will always point to the oldest supported version of the API.  Because of this, our recommendation is to always specify the requested version in order to avoid unexpected changes due to the deprecation and retirement schedule denoted above.\\n\\nIn order to receive a specific version of the API, you must provide a header value `X-Api-Version` in all requests to the v2 API.  More about the specifics of versioning can be found in the [versioning section of our documentation](https://dev.recurly.com/docs/versioning).\",\n  \"title\": \"Unversioned API Calls\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"API Upgrade Guide\"\n}\n[/block]\nYou may not need to address every change when migrating from your current version, but you will likely be affected by some of the breaking changes.  Please see the [API Release Notes](https://dev.recurly.com/page/api-release-notes) section of our documentation as a guide to help during the upgrade process.\n[block:api-header]\n{\n  \"title\": \"Client Library Upgrade Guides\"\n}\n[/block]\nPlease refer to the following upgrade guides for our officially supported client libraries. These guides aim to provide specific areas of focus when upgrading your application to support a new version of a client library.\n\n  * Ruby\nhttps://dev.recurly.com/page/ruby-upgrade-guide\n\n  * Python\nhttps://dev.recurly.com/page/python-upgrade-guide\n\n  * PHP\nhttps://dev.recurly.com/page/php-upgrade-guide\n\n  * .NET\nhttps://dev.recurly.com/page/net-upgrade-guide","slug":"recurly-v2-api-support-policy-and-roadmap","title":"Recurly API v2: Support Policy and Roadmap"}

Recurly API v2: Support Policy and Roadmap


The purpose of this page is to provide information pertaining to Recurly's support of the v2 API and its associated client libraries. The API Release, Deprecation, and Retirement Schedule, found [below](#api-version-release-deprecation-and-retirement-sch), is of particular importance. If you have any questions, please [reach out to our team](https://support.recurly.com/) at any time. [block:api-header] { "title": "Recurly API v2 Client Libraries" } [/block] Recurly provides client libraries in several programming languages, making it is possible to access the v2 API without making direct calls to the HTTP endpoints. Recurly supports official client libraries in Ruby, Python, PHP, and .NET. Unofficial, community supported client libraries are available in Java, Node.js, Go, and Elixir. See our [https://dev.recurly.com/docs/client-libraries](https://dev.recurly.com/docs/client-libraries) for more information. [block:callout] { "type": "warning", "body": "Please note that all client library related information in this document pertains specifically to the official client libraries." } [/block] [block:api-header] { "title": "API Releases and Backward-Compatibility" } [/block] Recurly provides new API releases continuously in order to deliver new features, to improve performance, to fix bugs, and to provide enhanced security. While our aim is to always provide these updates in a backward-compatible fashion, breaking changes are sometimes unavoidable. As such, we release new versions of our API from time to time in order to avoid disrupting existing customer integrations. Although we guarantee that new versions of the API will be supported and remain available for at least two years from release, it is important to maintain a regular upgrade schedule for your integration, migrating to the latest version of our API as often as possible. This will ensure that you benefit from new functionality, improved performance, and security updates as they become available. [block:api-header] { "title": "API Version Release, Deprecation, and Retirement Schedule" } [/block] [block:callout] { "type": "warning", "body": "API versions are deprecated two years after the date that the subsequent version is released ( rounded to the nearest month) and they are retired six months after the deprecation date." } [/block] * **Deprecation means that Recurly will no longer support, provide bug fixes, or patch security issues for a given API version** * **Retirement means that a given API version will no longer function.** *Example: If API version v2.3 is released on March 25th, 2015 and API version v2.4 is released August 7th, 2015, then v2.3 would be deprecated on September 1st, 2017, two years after the release of v2.4. Retirement of v2.3 would occur on Feb. 1st, 2018, six months after the deprecation date* [block:callout] { "type": "info", "body": "The following schedule provides release dates for currently supported versions of our API along with deprecation and retirement dates based on the policy noted above.\n\nClient library versions follow the same release, deprecation, and retirement schedule as their associated API version. In order to determine which version of the API your client library version is using, please refer to the [upgrade guides below](#client-library-upgrade-guides)" } [/block] [block:parameters] { "data": { "9-3": "May, 2021", "9-0": "2.15", "h-0": "API Version", "h-1": "Release Date", "h-2": "Deprecation Date", "h-3": "Retirement Date", "0-0": "2.6 (and lower)", "1-0": "2.7", "2-0": "2.8", "3-0": "2.9", "4-0": "2.10", "5-0": "2.11", "6-0": "2.12", "7-0": "2.13", "8-0": "2.14", "10-0": "2.16", "11-0": "2.17", "12-0": "2.18", "13-0": "2.19", "0-1": "May 2017 (and earlier)", "1-1": "June 2017", "2-1": "Oct. 2017", "3-1": "Nov. 2017", "4-1": "Jan. 2018", "5-1": "Apr. 2018", "6-1": "May 2018", "7-1": "June 2018", "8-1": "Aug. 2018", "9-1": "Sept. 2018", "10-1": "Oct. 2018", "11-1": "Dec. 2018", "12-1": "Feb. 2019", "13-1": "March 2019", "0-2": "July 1, 2019", "1-2": "Nov. 1, 2019", "2-2": "Dec. 1, 2019", "3-2": "Feb. 1, 2020", "4-2": "May 1, 2020", "5-2": "June 1, 2020", "6-2": "July 1, 2020", "7-2": "Sept. 1, 2020", "8-2": "Oct. 1, 2020", "9-2": "Nov. 1, 2020", "10-2": "Jan. 1, 2021", "11-2": "March 1, 2021", "12-2": "April 1, 2021", "13-2": "TBD", "13-3": "TBD", "0-3": "Feb 1, 2020", "1-3": "May 1, 2020", "2-3": "June 1, 2020", "3-3": "Aug. 1, 2020", "4-3": "Nov. 1, 2020", "5-3": "Dec. 1, 2020", "6-3": "Jan 1, 2021", "7-3": "March 1, 2021", "8-3": "April 1, 2021", "10-3": "July 1, 2021", "11-3": "Sept. 1, 2021", "12-3": "Oct. 1, 2021" }, "cols": 4, "rows": 14 } [/block] [block:callout] { "type": "warning", "body": "An unversioned call will always point to the oldest supported version of the API. Because of this, our recommendation is to always specify the requested version in order to avoid unexpected changes due to the deprecation and retirement schedule denoted above.\n\nIn order to receive a specific version of the API, you must provide a header value `X-Api-Version` in all requests to the v2 API. More about the specifics of versioning can be found in the [versioning section of our documentation](https://dev.recurly.com/docs/versioning).", "title": "Unversioned API Calls" } [/block] [block:api-header] { "title": "API Upgrade Guide" } [/block] You may not need to address every change when migrating from your current version, but you will likely be affected by some of the breaking changes. Please see the [API Release Notes](https://dev.recurly.com/page/api-release-notes) section of our documentation as a guide to help during the upgrade process. [block:api-header] { "title": "Client Library Upgrade Guides" } [/block] Please refer to the following upgrade guides for our officially supported client libraries. These guides aim to provide specific areas of focus when upgrading your application to support a new version of a client library. * Ruby https://dev.recurly.com/page/ruby-upgrade-guide * Python https://dev.recurly.com/page/python-upgrade-guide * PHP https://dev.recurly.com/page/php-upgrade-guide * .NET https://dev.recurly.com/page/net-upgrade-guide