--- name: recurly description: "Use when the user wants to manage recurring billing and subscriptions. Covers plans, accounts, invoices, and transactions via Recurly." version: "0.1.0" license: MIT category: payments triggers: - recurly - payment - pay - bill - invoice - subscription - billing - charge - refund - checkout --- current-ga-version)." version: "0.1.0" license: MIT --- # Recurly ## When to Use This Plugin Use this plugin when the user asks about: - Plans - Accounts - Invoices - Transactions ## Versioning The V3 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. `v2021-02-25`. > *WARNING*: Specifying a version is required to get a successful response. Each request should specify a version using the `Accept` header: * `Accept: application/vnd.recurly.v2021-02-25` * `Accept: application/vnd.recurly.v2021-02-25+json` All responses will include a `Recurly-Version` header with the API version used to process the request: ``` Recurly-Version: recurly.v2021-02-25 ``` Recurly's client libraries correspond with API versions as listed below.

API Version	Client Library Version
v2021-02-25	4.x
v2019-10-10	3.x

Client library releases: * [Node.js](https://github.com/recurly/recurly-client-node/releases) * [Python](https://github.com/recurly/recurly-client-python/releases) * [.NET](https://github.com/recurly/recurly-client-dotnet/releases) * [Ruby](https://github.com/recurly/recurly-client-ruby/releases) * [Java](https://github.com/recurly/recurly-client-java/releases) * [PHP](https://github.com/recurly/recurly-client-php/releases) * [Go](https://github.com/recurly/recurly-client-go/releases) Client libraries follow semantic versioning. For example, [Ruby client library version 3.18.1](https://github.com/recurly/recurly-client-ruby/releases/tag/3.18.1) represents major version `3`, minor version `18` with patch `1`. We encourage you to update to the latest version of the API and corresponding client library, as most recent versions are more performant than their predecessors. See the [changelog](https://recurly.com/developers/api/changelog.html) for a comprehensive list of changes introduced in the latest API version. ### Default Versions Specifying a version is required to get a successful response. If you wish to receive the latest version and are willing to accept the risk of breaking changes, you may specify a version of `latest`. The following media types will default the newest version of the API: * `application/vnd.recurly.latest` * `application/vnd.recurly.latest+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.v2016-03-01", "application/vnd.recurly.v2016-04-27", "application/vnd.recurly.v2016-07-27", "application/vnd.recurly.v2016-12-15", "application/vnd.recurly.v2017-01-12", "application/vnd.recurly.v2017-09-30", "application/vnd.recurly.v2018-01-24", "application/vnd.recurly.v2018-05-10", "application/vnd.recurly.v2018-06-06", "application/vnd.recurly.v2018-08-09", "application/vnd.recurly.v2019-10-10", "application/vnd.recurly.v2021-02-25" ] } } ``` ## Error Messages Error messages sent via the Recurly API are generally directed at developers and those who are familiar with API technology. When using the 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 the target system to be better suited to the audience of the system. Please see [transaction error codes](https://recurly.com/developers/pages/api-transaction-errors.html) 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](https://recurly.com/developers/api/changelog.html#v2021-02-25---current-ga-version). ## Bundled skills | Skill | What it does | |-------|--------------| | `recurly-quickstart` | Probe the API and learn the available subcommands. | | `recurly-accounts` | User wants to view, create, update, delete accounts | | `recurly-acquisitions` | User wants to view acquisitions | | `recurly-add-ons` | User wants to view add ons | | `recurly-business-entities` | User wants to view business entities | | `recurly-coupons` | User wants to view, create, update, delete coupons | | `recurly-credit-payments` | User wants to view credit payments | | `recurly-custom-field-definitions` | User wants to view custom field definitions | | `recurly-dunning-campaigns` | User wants to view dunning campaigns | | `recurly-export-dates` | User wants to view export dates | | `recurly-external-invoices` | User wants to view external invoices | | `recurly-external-products` | User wants to view, create, update, delete external products | | `recurly-external-subscriptions` | User wants to view, create, update external subscriptions | | `recurly-general-ledger-accounts` | User wants to view, create, update general ledger accounts | | `recurly-gift-cards` | User wants to view, create gift cards | | `recurly-invoice-templates` | User wants to view invoice templates | | `recurly-invoices` | User wants to view, update invoices | | `recurly-items` | User wants to view, create, update, delete items | | `recurly-line-items` | User wants to view, delete line items | | `recurly-measured-units` | User wants to view, create, update, delete measured units | | `recurly-performance-obligations` | User wants to view performance obligations | | `recurly-plans` | User wants to view, create, update, delete plans | | `recurly-price-segments` | User wants to view price segments | | `recurly-purchases` | User wants to create purchases | | `recurly-shipping-methods` | User wants to view, create, update, delete shipping methods | | `recurly-sites` | User wants to view sites | | `recurly-subscriptions` | User wants to view, create, update, delete subscriptions | | `recurly-transactions` | User wants to view transactions | | `recurly-unique-coupon-codes` | User wants to view, delete unique coupon codes | | `recurly-usage` | User wants to view, update, delete usage | ## Binary The plugin ships as a single statically-linked native binary per platform. Scripts and other plugins receive the binary path in the `RECURLY_BIN` environment variable. ```bash $RECURLY_BIN --help $RECURLY_BIN ping ```