v2017-09-30 | Recurly Developer Hub

Recurly Partner API (v2017-09-30)

Download OpenAPI specification:Download

Getting Started

Versioning

The Partner API is versioned to allow stability for integrators and flexibility for Recurly to continue making improvements.

The versions follow a format that incorporates the approximate date the changes were released in a YYYY-MM-DD format, e.g. v2017-09-30.

Each request should specify a version using the Accept header:

  • Accept: application/vnd.recurly.v2017-09-30
  • Accept: application/vnd.recurly.v2017-09-30+json

All responses will include a Recurly-Version header with the API version used to process the request:

Recurly-Version: recurly.v2017-09-30

Default Versions

By default any non-versioned request will default to the newest version of the API. Users of the API are strongly encouraged to specify the requested version to avoid unexpected changes when new versions are added.

The following media types would will also default the newest version of the API:

  • application/json
  • application/vnd.recurly
  • application/vnd.recurly+json

Deprecation

Responses for a deprecated version request will return two headers:

Recurly-Deprecated: TRUE
Recurly-Sunset-Date: 2017-06-01T00:00:00+00:00

The sunset date is an ISO-8601 formatted date time after which the version will no longer be accessible.

Unsupported Versions

A request for an unsupported version will return a status code of 406 and the body will include a list of supported versions:

{
  "error": {
    "type": "invalid_api_version",
    "message": "That accept header isn't in the format we use to specify an API version. Try one of these instead:",
    "acceptable_accept_headers": [
      "application/vnd.recurly.v2017-01-12",
      "application/vnd.recurly.v2017-09-30"
    ]
  }
}

Error Messages

Error messages sent via the Recurly Partner API are generally directed at developers and those who are familiar with API technology. When using the Partner API and passing error messages to target systems, be mindful that these messages may not make sense in the context of the target system. Please consider changing these messages in target system to be better suited to the audience of the system.

Please see transaction error codes for more details.

Pagination

Response Schema

Every GET listing endpoint returns a response with the same schema:

{
  "object":   "list",         // Always "list"
  "has_more": true,           // false if this is the last page of data
  "next":     "https://...",  // A URL pointing to the next page of data
  "data":     []              // The data for this page as an array
}

To page through every record, your code should continually call the URL at next until has_more is false.

Query Parameters

Most GET listing endpoints take query parameters that allow filtering and sorting the results. Some endpoints have additional parameters, which are documented on the respective endpoints, but most support the following parameters:

  • ids: A comma separated list of ids to match.
  • limit: The number of records to return per page.
  • order: The sort order of records.
  • sort: The date field to use in sorting.
  • begin_time: The start datetime to filter (ISO 8601).
  • end_time: The end datetime to filter (ISO 8601).

Counting with HEAD

Every GET listing endpoint also supports the HEAD HTTP method. Making a head request to the endpoint results in an empty body and an additional Recurly-Total-Records header. This is a count of the total number of records that the endpoint will return, taking into account the current filtering query parameters.

Limits

In order to provide a fast response time to all our customers, we may rate limit excessive requests. By default, new Recurly sites have the following API rate limits:

  • Sandbox sites: 400 requests/min. All requests count towards the rate limit.
  • Production sites: 1,000 requests/min. Only GET requests count towards the rate limit.

Once your site moves into production mode, Recurly will only rate limit GET requests. New subscriptions, account modifications, and other requests using POST, PUT, or DELETE methods will not count against your rate limit.

The rate limit is calculated over a sliding 5 minute window. This means a production site could make 4,000 requests within one minute and not hit the rate limit so long as the site made less than 1,000 requests during the prior 4 minutes.

If an API request exceeds the rate limit, the API will return a 429 Too Many Requests HTTP status. If your business needs a higher limit, please contact support.

The rate limit applied to your client can be determined with the X-RateLimit-Limit header, and the number of remaining requests is sent in the X-RateLimit-Remaining header. Finally, the X-RateLimit-Reset header contains an integer value representing the time, measured in seconds since the UNIX Epoch, at which the request count will be reset.

Change Log

A list of changes for this version can be found in the changelog.

Authentication

api_key

Enter the API key as the username and set the password to an empty string. You can locate and manage your API keys from the API Credentials page.

Security Scheme Type HTTP
HTTP Authorization Scheme basic
➔ Next to Account