Authenticate by including your Recurly private API key in the 'Authorization' header as 'Basic {base64(api_key:)}'; generate API keys in Recurly Admin Console > Integrations > API Credentials.
Base URL is https://v3.recurly.com; all requests must include 'Accept: application/vnd.recurly.v2021-02-25' (or current version date) and 'Content-Type: application/json' headers.
Create an account first by POSTing to /accounts with 'code' (your unique identifier for the customer), 'email', 'first_name', and 'last_name'; the account must exist before creating a subscription.
Create a subscription by POSTing to /subscriptions with 'plan_code' (referencing a plan configured in Recurly), 'account' object (with 'code' referencing the account), and 'currency'; include 'billing_info' with payment method details or a token from Recurly.js.
Configure dunning in Recurly Admin Console > Settings > Dunning Management — define retry schedules per payment method type (credit card, ACH, PayPal); dunning configuration is UI-based and does not require API calls for the schedule itself.
Monitor failed payments and dunning status via webhooks; configure endpoint URLs in Admin Console > Integrations > Webhooks for events like 'failed_payment_notification' and 'subscription_expired_notification'.
Known gotchas
Recurly requires the API version header ('Accept: application/vnd.recurly.v2021-02-25') on every request; omitting it or using an outdated version string can result in deprecated behavior or errors — pin your integration to a specific version date and update deliberately.
Plan codes and add-on codes are configured in the Recurly UI and must exist before they can be referenced in the API; attempting to create a subscription with a non-existent plan_code returns a validation error that can be confusing if you're expecting the plan to be auto-created.
Dunning configuration affects all subscriptions globally by default; if you have different customer segments requiring different retry strategies, you must configure separate dunning campaigns in Recurly and assign them to accounts or plans — the global default is easy to overlook when going live.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp