Recurly Partner API (v2017-09-30)
Download OpenAPI specification:Download
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 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.
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.
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.
A list of changes for this version can be found in the changelog.
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 |