A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Recurly API is how an app or AI agent runs subscription billing on a site: creating an account, starting or canceling a subscription, collecting or refunding an invoice, and applying a coupon. Access is granted through a private API key that carries full access to the site it belongs to, because Recurly has no granular scopes or read-only key type, so the only built-in boundary is which site the key is tied to. A change to a record can be pushed to a configured endpoint as a notification, so an integration learns about activity without polling.
How an app or AI agent connects to Recurly determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the credential behind it. A private API key carries full access to the site it belongs to, so the boundary an agent works within comes from how that key is given out and what sits in front of it.
The REST API takes JSON request bodies, returns JSON, and pages through lists with a cursor, at https://v3.recurly.com (or https://v3.eu.recurly.com for the EU data center). A call authenticates with a private API key over HTTP Basic auth, and every request must name a dated API version in the Accept header, like application/vnd.recurly.v2021-02-25.
Recurly POSTs a notification to an HTTPS endpoint configured in the site settings whenever a chosen event happens, like a subscription renewing or a payment failing. Payloads are available in JSON or XML, set per endpoint, and an endpoint can be limited to only the notification types it cares about. A JSON payload carries the event type and object identifiers, which an integration uses to re-fetch the current object through the API.
A private API key authenticates server-side calls over HTTP Basic auth, sent as the username with a blank password. It carries full access to the site it belongs to: Recurly has no per-method scopes or read-only key type, so any key can call any method, read or write. A site can hold several private keys (5 on Core or sandbox sites, 10 on Professional), so a key can be issued per integration and rotated independently. A private key must never be exposed in client code.
A separate public key is used only by Recurly.js and the mobile SDKs to tokenize card details in the browser or app, so raw card data never reaches an integration's own servers. It cannot read or change data through the API and is not an alternative way to authenticate API calls.
The Recurly API is split into areas an agent can act on, like accounts, subscriptions, invoices, plans, transactions, and coupons. Each area has its own methods, and writes in some areas charge cards, refund money, or cancel a customer's billing.
Methods for working with customer accounts.
Methods for working with an account's stored payment details.
Methods for working with recurring subscriptions.
Methods for working with invoices.
Methods for working with charges and credits on an account.
Methods for working with subscription plans.
Methods for reading payment transactions.
Methods for working with discount coupons.
Methods for creating a checkout in a single call.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
AccountsMethods for working with customer accounts.5 | ||||||
| GET | /accounts | List the accounts on a site. | read | — | Current | |
Read-only. Recurly has no per-method scopes; a private API key can call this. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /accounts | Create a customer account. | write | — | Current | |
A core write. Recurly has no per-method scopes; a private API key carries full access. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook event new_account_notificationRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /accounts/{account_id} | Fetch a single account by id or by code (prefixed with code-). | read | — | Current | |
Read-only. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /accounts/{account_id} | Update an account's details. | write | — | Current | |
A core write. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook event updated_account_notificationRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /accounts/{account_id} | Deactivate an account, ending its billing relationship. | write | — | Current | |
Reversible with the reactivate method; cancels the account's active subscriptions. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook event canceled_account_notificationRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Billing infoMethods for working with an account's stored payment details.3 | ||||||
| GET | /accounts/{account_id}/billing_info | Fetch the account's stored billing information. | read | — | Current | |
Read-only. Card numbers are returned only as a masked last four, never in full. Acts onbilling_info Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /accounts/{account_id}/billing_info | Set or replace the payment method on an account. | write | — | Current | |
Sets the payment method that future charges are taken from. Raw card data is normally tokenized client-side. Acts onbilling_info Permission (capability)None required VersionAvailable since the API’s base version Webhook event billing_info_updated_notificationRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /accounts/{account_id}/billing_info | Remove the stored billing information from an account. | write | — | Current | |
Leaves the account with no payment method until one is set again. Acts onbilling_info Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SubscriptionsMethods for working with recurring subscriptions.7 | ||||||
| GET | /subscriptions | List the subscriptions on a site. | read | — | Current | |
Read-only. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions | Create a subscription on an account for recurring billing. | write | — | Current | |
Starts recurring billing and can generate an immediate invoice and charge. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook event new_subscription_notificationRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /subscriptions/{subscription_id} | Fetch a single subscription. | read | — | Current | |
Read-only. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /subscriptions/{subscription_id} | Update a subscription's details that do not change pricing immediately. | write | — | Current | |
Plan and quantity changes go through the subscription change endpoint, not this one. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook event updated_subscription_notificationRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /subscriptions/{subscription_id}/cancel | Cancel a subscription so it expires at the end of the current term. | write | — | Current | |
The subscription stays active until term end, then expires; reactivate undoes it before then. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook event canceled_subscription_notificationRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /subscriptions/{subscription_id} | Terminate a subscription immediately, optionally refunding. | write | — | Current | |
Ends the subscription now and can issue a full or prorated refund depending on the refund parameter. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook event expired_subscription_notificationRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions/{subscription_id}/change | Change a subscription's plan, quantity, or add-ons, with proration. | write | — | Current | |
Can charge or credit immediately depending on the timeframe and proration settings. Acts onsubscription_change Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InvoicesMethods for working with invoices.5 | ||||||
| GET | /invoices | List the invoices on a site. | read | — | Current | |
Read-only. Acts oninvoice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /invoices/{invoice_id} | Fetch a single invoice. | read | — | Current | |
Read-only. A PDF of the invoice is available at the .pdf variant of this path. Acts oninvoice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /invoices/{invoice_id}/collect | Attempt to collect payment on a pending or past-due invoice. | write | — | Current | |
Charges the account's payment method; fires a payment notification on success or failure. Acts oninvoice Permission (capability)None required VersionAvailable since the API’s base version Webhook event successful_payment_notificationRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /invoices/{invoice_id}/refund | Refund part or all of a paid invoice. | write | — | Current | |
Moves real money back to the customer; refund can be by amount or by line item. Acts oninvoice Permission (capability)None required VersionAvailable since the API’s base version Webhook event successful_refund_notificationRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /invoices/{invoice_id}/void | Void an open invoice that has no payment applied. | write | — | Current | |
Only valid on an invoice with nothing collected on it. Acts oninvoice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Line itemsMethods for working with charges and credits on an account.3 | ||||||
| GET | /line_items | List the line items (charges and credits) on a site. | read | — | Current | |
Read-only. Acts online_item Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /accounts/{account_id}/line_items | Add a one-time charge or credit to an account. | write | — | Current | |
Creates an uninvoiced charge or credit that a later invoice picks up. Acts online_item Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /line_items/{line_item_id} | Remove an uninvoiced (pending) line item. | write | — | Current | |
Only a line item not yet attached to an invoice can be removed. Acts online_item Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PlansMethods for working with subscription plans.4 | ||||||
| GET | /plans | List the subscription plans on a site. | read | — | Current | |
Read-only. Acts onplan Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /plans | Create a subscription plan. | write | — | Current | |
Adds to the catalog every new subscription draws from. Acts onplan Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /plans/{plan_id} | Fetch a single plan. | read | — | Current | |
Read-only. Acts onplan Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /plans/{plan_id} | Update a plan's details. | write | — | Current | |
Affects new subscriptions and renewals on the plan. Acts onplan Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TransactionsMethods for reading payment transactions.2 | ||||||
| GET | /transactions | List the payment transactions on a site. | read | — | Current | |
Read-only. Transactions are created by collection and refund actions, not by a direct create method. Acts ontransaction Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /transactions/{transaction_id} | Fetch a single transaction. | read | — | Current | |
Read-only. Acts ontransaction Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CouponsMethods for working with discount coupons.3 | ||||||
| GET | /coupons | List the coupons on a site. | read | — | Current | |
Read-only. Acts oncoupon Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /coupons | Create a discount coupon. | write | — | Current | |
Creates a discount that can be redeemed on accounts and subscriptions. Acts oncoupon Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /accounts/{account_id}/coupon_redemptions/active | Redeem a coupon onto an account so its discount applies. | write | — | Current | |
Reduces what the account is billed on matching charges. Acts oncoupon_redemption Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PurchasesMethods for creating a checkout in a single call.3 | ||||||
| POST | /purchases | Create a purchase: account, subscriptions, charges, and payment in one call. | write | — | Current | |
Charges the card and creates the resulting invoice, subscriptions, and transactions together. Acts onpurchase Permission (capability)None required VersionAvailable since the API’s base version Webhook event successful_payment_notificationRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /purchases/preview | Preview a purchase to see the resulting invoice without charging. | read | — | Current | |
No money moves; returns the invoice that a real purchase would produce. Acts onpurchase Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /purchases/authorize | Authorize a purchase, holding funds without capturing them. | write | — | Current | |
Places a hold on the card; capture the held funds with the capture method. Acts onpurchase Permission (capability)None required VersionAvailable since the API’s base version Webhook event transaction_authorized_notificationRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Recurly can notify an app when something happens on a site, like a subscription renewing, a payment succeeding, or an invoice closing. It sends a notification naming the event and the object it concerns, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
new_account_notification | A new account was created on the site. | /accounts |
updated_account_notification | An account's details were changed. | /accounts/{account_id} |
canceled_account_notification | An account was closed or deactivated. | /accounts/{account_id} |
billing_info_updated_notification | An account's stored billing information was added or changed. | /accounts/{account_id}/billing_info |
new_subscription_notification | A new subscription was created on an account. | /subscriptions |
updated_subscription_notification | A subscription was changed. | /subscriptions/{subscription_id} |
canceled_subscription_notification | A subscription was canceled and will expire at term end. | /subscriptions/{subscription_id}/cancel |
expired_subscription_notification | A subscription ended, either at term end or by immediate termination. | /subscriptions/{subscription_id} |
successful_payment_notification | A payment was approved and collected. | /invoices/{invoice_id}/collect/purchases |
successful_refund_notification | A refund was processed back to the customer. | /invoices/{invoice_id}/refund |
transaction_authorized_notification | An authorize-and-capture style payment was authorized, holding funds. | /purchases/authorize |
Recurly limits how fast an app can call, by a request count measured over a rolling window, with separate ceilings for sandbox and production sites.
Recurly meters requests by count over a rolling 5 minute window, not by a per-method cost. A new sandbox site allows 400 requests per minute and counts every request, while a new production site allows 1,000 requests per minute and counts only GET and HEAD requests, so writes on a production site do not draw down the limit. Because the window is rolling, a production site can burst well above the per-minute figure in a single minute as long as the 5 minute total stays under the ceiling. Going over returns HTTP 429, and every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers to track headroom.
List endpoints are cursor-based. The limit parameter sets the page size from 1 to 200 (default 20), order is asc or desc (default desc), and sort chooses the field to order by, usually created_at or updated_at. The response Link header carries the URL of the next page, and a has_more field signals whether more pages remain. The client libraries expose this as an auto-paging iterator.
A list page returns at most 200 records, the maximum value of limit. Times in begin_time and end_time filters use ISO 8601. Webhook notifications can be delivered as JSON or XML, configured per endpoint.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | The request could not be understood, for example malformed JSON or an invalid content type. | Read the message, fix the request body or headers, and resend. |
| 401 | unauthorized / invalid_api_key | No valid API key was provided, or the key was rejected. | Confirm a current private API key is sent as the Basic auth username, and rotate it if it may be compromised. |
| 403 | invalid_permissions | The key is valid but not allowed to perform this action on this site. | Use a key for the correct site, and confirm the site has the feature enabled. |
| 404 | not_found | The requested object does not exist or is not visible to this site. | Verify the id or code, and confirm the object lives on the same site as the key. |
| 422 | validation / transaction | The parameters failed validation, or a payment was declined. A transaction error carries a transaction_error object describing the decline. | Read params for the field errors, or transaction_error for a decline, fix the input, and ask for a different payment method where needed. |
| 406 | invalid_api_version / unknown_api_version | The Accept header named no version or a version Recurly does not recognize. | Send a supported dated version in the Accept header, like application/vnd.recurly.v2021-02-25. |
| 429 | rate_limited | Too many requests arrived within the rolling rate-limit window. | Back off using the X-RateLimit-Reset header and retry, and smooth the request rate. |
| 500 | internal_server_error | An error on Recurly's side, which can also appear as service_not_available. It is rare. | Retry with backoff, and contact Recurly support if it persists. |
Recurly pins a dated version of its API, requested per call, so a change ships under a new dated version and existing integrations keep working against the one they target.
Recurly pins a dated API version requested per call in the Accept header, like application/vnd.recurly.v2021-02-25, and a response echoes it in the Recurly-Version header. This version corresponds to the 4.x client libraries.
The version targeted by the 3.x client libraries, superseded by v2021-02-25.
An earlier dated version introducing checkout-style purchases and account relationships.
Added the ability to pause and resume a subscription.
Target a dated version in the Accept header and move up deliberately.
Recurly API changelog ↗Bollard AI sits between a team's AI agents and Recurly. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged. This matters more with Recurly than most apps, because a Recurly private API key carries full access on its own.