v2.13 | Recurly Developer Hub

Recurly V2 API (2.13)

Download OpenAPI specification: Download

Getting Started

Welcome to the reference documentation for Recurly's XML API v2. Here you will find a complete reference for all API v2 operations.

If you're building a new product, or just getting started with Recurly, we recommend using our newer JSON API v3.

Now let's get started with API v2.

Authentication

API Authentication (HTTP Basic)

Recurly uses HTTP Basic Authentication—your Private API key is securely encrypted by the SSL channel.

If you are testing the API calls via the command line with cURL, try:

curl -H 'Accept: application/xml' \
     -H 'X-Api-Version: 2.13' \
     -H 'Content-Type: application/xml; charset=utf-8' \
     -u '[apikey]' \
    https://[subdomain].recurly.com/v2/accounts

Replace [apikey] and [subdomain] with the appropriate values for your site.

Additional Request Headers

Accept Header

Recurly API v2 returns results as XML. Your requests should always include the header requesting the results as XML:

Accept: application/xml

Content-Type Header

When sending data to Recurly in a POST or PUT request, your request must specify the content type of your request:

Content-Type: application/xml; charset=utf-8

X-Api-Version Header

When sending data to Recurly, your request should specify the API version you're attempting to interact with:

X-Api-Version: 2.13

Public API Key

Recurly uses two types of API keys: public and private. The Public API key is used by Recurly.js to identify its requests as belonging to your Recurly site. This key can be safely included in Javascript code.

Recurly provides each site with one Public Key. The Public API Key can be regenerated on the API Credentials page.

Private API Keys

Treat your Private API Keys like passwords!

The API key allows access to your site's data. Do not include it in Javascript code exposed to browsers.

Recurly supports the use of multiple Private API keys, which can be used to integrate third party services using unique, controlled credentials.

Regenerating Private API Keys

Your API key can be regenerated by clicking on the Regenerate button on the API credentials page. When you generate a private API key, you have two options:

  1. Block the old key immediately. This is primarily recommended when the security of a key has been compromised.
  2. Allow the old key access for 12 hours. This is primarily used when updating systems and a smooth transition between keys is needed.

Read-Only Keys

When creating a private key, you will have the option to set the key to "read-only". This means the API key may make GET requests but cannot not PUT, POST or DELETE requests.

API Versioning

Recurly strives to provide developers with stable APIs to integrate against while still being able to provide new and expanded functionality. To balance these two goals we provide different API versions and only add new features to the latest version of the API.

Recurly offers the following API versions: 2.13, 2.12, 2.11,...

Requesting A Version

API Version Deprecation

As a matter of policy, API versions will remain supported by Recurly for 2 years after they are released. After this time period, the API versions will be deprecated and no longer supported, but will still function.

Pagination

Next Link

The amount of records returns within a single API request defaults to 50. It may be changed to a maximum of 200 using a per_page query parameter, e.g. to return 200 accounts at a time:

https://your-subdomain.recurly.com/v2/accounts?per_page=200

When there are more records remaining than fit in the current response, the Link header is specified with the URI to the next page of results.

Counting Records

Starting with API version 2.6, you must explicitly make a HEAD request to get the server count. Endpoints that return a list of resources will respond to this request and include a header indicating the total number of records available.

Examples

This will return accounts that were created on or before 2016-01-01 0:00 UTC in descending order of creation date:

[https://your-subdomain.recurly.com/v2/accounts?sort=created_at&order=desc&end_time=2016-01-01](https://your-subdomain.recurly.com/v2/accounts?sort=created_at&order=desc&end_time=2016-01-01)

HTTP Status Codes

SUCCESSFUL STATUS CODES (2XX)

200 OK The request was successful.

201 Created The resource was successfully created. Confirms a success when creating a new account, credit, subscription, etc.

CLIENT ERROR STATUS CODES (4XX)

400 Bad Request The request was invalid or could not be understood by the server.

401 Unauthorized Your API key is missing or invalid.

SERVER ERROR STATUS CODES (5XX)

500 Internal Server Error The server encountered an error while processing your request and failed.