Please note: This blog has been updated to reflect that Recurly’s API v2.6 will sunset rather than reach end of life. The text below has been updated to reflect this change. 

In March, we discussed how Recurly approaches the maintenance of our API, including changes, updates, performance improvements and other essentials that minimize friction and provide a top-notch development experience. API consumers who implement continuous API upgrades are afforded a variety of advantages, which our previous blog outlined and which we encourage you to review.

API providers as well can help facilitate our customers in upgrading their API. At Recurly, our policy is that API versions are deprecated two years after the date that the subsequent version is released (rounded to the nearest month).

We have endeavored to be exceedingly transparent with our customers and partners about this approach. This lets our API consumers plan ahead for when they’ll need to upgrade their current API based on their business needs and our sunset schedule.

Pursuant to this policy, please be aware that Recurly’s API v2.6 and lower will have sunset on the following dates.

July 1, 2019 – Sunset On this date, Recurly will no longer support, provide bug fixes, or patch security issues for API versions 2.6 and lower

If your business is using Recurly’s API v2.6 and lower, it is critical that you upgrade your integration in order to avoid degradation or complete loss of service. Doing so will ensure that your integration continues to function as expected and that you will benefit from the most current features and functionality that the platform has to offer.

If, for any reason, you are unable to upgrade to the most current version before the dates stated above, you will need to upgrade to version 2.7 or above at the very least. 

Upgrade Details

Our customers integrate with the Recurly API via three methods. The majority of our customers use our official client libraries, which provide language specific implementations and helper functions that interact directly with the HTTP API. Other customers use one of the many community supported client libraries if they use a programming language that Recurly does not support in an official capacity.  And finally, some customers choose to integrate directly with the HTTP API. The following sections provide specific information about upgrading your API depending on the integration method(s) that you currently use.

Upgrade Guide for Official Client Library Users

If you are using any of the official client libraries currently maintained by Recurly, please follow the upgrade guide for your programming language here.

NOTE: Although client libraries use and are dependent on specific versions of the API, they are subject to an independent versioning scheme. The guides in the link above provide version mapping tables to help you determine which version of a given client library is needed for a specific version of the API.

Upgrade Guide for HTTP API Users

Update the `X-Api-Version` header in all requests to the v2 API to indicate the version of the API that you are targeting. More about versioning can be learned from the versioning section of our documentation.

NOTE: If you do not indicate a specific version of the API, we can not guarantee that the default version returned will be supported or available. Therefore, it is critical that you explicitly request a specific API version.

To understand what is changing between your current version and the version to which you are migrating, see the following guide.

Upgrade Guide for Unofficial Client Library Users

Unfortunately, we can not provide specific upgrade instructions for the community-provided client libraries as they are supported and maintained outside of Recurly. Our recommendation is to contact the maintainer(s) of the unofficial client library for further instruction. At the very least, they should be able to tell you which version of the client library is required for the corresponding API version that you are targeting. If you are having issues contacting the maintainer, please contact us and we may be able to assist.

Reason for This Service Update

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, and we cannot support all versions of the API indefinitely.

Partner to Your Success

Our API offering is critical to the success of our customers and partners as it provides the primary entry point into our industry-leading subscription management platform. We take pride in providing our API in a way that empowers our customers to integrate quickly, while also minimizing friction and providing a top-notch development experience along the way.

You can read more about our API policy and see a complete schedule of deprecation and sunset dates for all versions of our API on our Support Policy and Roadmap page.

Questions?  Please contact our Support Team.