• Content

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 and Sunset Schedule, found below, is of particular importance.

If you have any questions, please reach out to our team.

Recurly API v2 Client Libraries

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 Client libraries for more information.

Please note that all client library related information in this document pertains specifically to the official client libraries.

API Releases and Backward-Compatibility

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.

API Version Release and Sunset Schedule

Recurly sunsets API versions two years after the date that the subsequent version is released (rounded to the nearest month). Sunset means that Recurly will no longer support, provide bug fixes, or patch security issues for a given API version.

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 sunset on September 1st, 2017, two years after the release of v2.4.*

The following schedule provides release dates for currently supported versions of our API along with sunset dates based on the policy noted above.\n\nClient library versions follow the same release and sunset 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.

API Version Release Date Sunset Date
2.29 August 2020 TBD
2.28 July 2020 September 2022
2.27 May 2020 August 2022
2.26 March 2020 June 1, 2022
2.25 Feb. 2020 April 1, 2022
2.24 Nov. 2019 March. 1, 2022
2.22 Aug. 2019 December. 1, 2021
2.21 June 2019 Sept. 1, 2021
2.20 May 2019 July 1, 2021
2.19 March 2019 June 1, 2021
2.18 Feb. 2019 April 1, 2021
2.17 Dec. 2018 March 1, 2021
2.16 Oct. 2018 Jan. 1, 2021
2.15 Sept. 2018 Nov. 1, 2020
2.14 Aug. 2018 Oct. 1, 2020
2.13 June 2018 Sept. 1, 2020
2.12 May 2018 July 1, 2020
2.11 Apr. 2018 June 1, 2020
2.10 Jan. 2018 May 1, 2020
2.9 Nov. 2017 Feb. 1, 2020
2.8 Oct. 2017 Dec. 1, 2019
2.7 June 2017 Nov. 1, 2019
2.6 (and lower) May 2017 (and earlier) July 1, 2019

Unversioned API Calls

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.

API Upgrade Guide

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 section of our documentation as a guide to help during the upgrade process.

Client Library Upgrade Guides

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.