Recurly
Connect a Recurly site with a private API key so Checkbox reads your plans, trials and subscription events, and see what it can't read from Recurly.
Checks only. Checkbox checks your pages, emails and cancellation flow, and reads your Recurly plans and subscription events. Checkbox never changes anything in Recurly. For a test subscription, use a generic test run. Reminders need time travel, which only Stripe test runs have.
Checkbox reads your plans and trials through the Recurly API (version v2021-02-25), and turns Recurly webhooks (new subscriptions, trial-ending and renewal reminders, renewals, scheduled price changes, cancellations) into lifecycle events. The reminder and cancellation checks use those events, and so do Notices.
Connect
- Register the site with
platform: "recurly":
curl https://app.checkbox.site/v1/sites \
-u "$CHECKBOX_SECRET_KEY:" \
-H "Content-Type: application/json" \
-d '{ "url": "https://acme-saas.example", "platform": "recurly" }'import Checkbox from '@checkbox-site/node';
const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);
const site = await checkbox.sites.create({ url: 'https://acme-saas.example', platform: 'recurly' });
console.log(site.id);import os
from checkbox import Checkbox
checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])
site = checkbox.sites.create(url="https://acme-saas.example", platform="recurly")
print(site["id"])- Create a private API key in Recurly: Integrations → API Credentials → Add Private API Key (the direct link is
https://app.recurly.com/go/developer/api_keys). Name it Checkbox and save. You need a Recurly role with the Integration permission. Each Recurly site has its own keys: use one from the site you want checked. - In the dashboard, open Site → Settings → Billing connection, choose Recurly, paste the key, and pick the data center (Europe if your site is hosted in Recurly's EU data center, otherwise United States). Checkbox reads your plans once to check the key, then stores it encrypted. With the API, call
connectBillingPlatformwith{ "platform": "recurly", "credentials": { "apiKey": "…", "region": "us" } }(regionisusoreu; it defaults tous). - Add the webhook. After you connect, the dashboard shows the webhook URL, a username and password, and the notifications to send (they're also under Billing connection → Recurly webhook, and in
webhook_setupin the API response). In Recurly, open Integrations → Webhooks, add an endpoint with the URL, choose the JSON format, turn on HTTP basic authentication with the username and password, and select the notifications. Turn on the trial-ending and renewal reminder notifications in the webhook settings too. - Recommended: copy the endpoint's secret key from the Webhooks page in Recurly and paste it under Billing connection → Recurly webhook. Checkbox then also checks the
recurly-signatureon every delivery and refuses deliveries more than 5 minutes old.
About the API key
Recurly's private API keys give full access to your Recurly site: Recurly doesn't offer read-only keys on every plan. Checkbox only sends read requests (GET and HEAD) to v3.recurly.com or v3.eu.recurly.com, and never follows redirects. To limit the risk:
- Create a separate key named Checkbox, so you can revoke it any time without affecting other apps.
- If your key form offers a read-only option, choose it.
- You can regenerate or delete the key in Recurly at any time. Checkbox stops reading as soon as it's revoked.
What Checkbox reads
| Setting | Read from Recurly? |
|---|---|
| Plans: price per currency, billing interval | Yes. Ramp-priced plans are read at their first price |
| Free trials (length, and whether a payment method is needed) | Yes, from each plan |
| Fixed-term plans (a set number of billing cycles) and plans that don't auto-renew | Yes. Plans with auto-renew off aren't checked as subscriptions |
| Subscription counts by state | Yes. Counts only, no customer data |
| Subscription events: new, trial ending, renewal reminders, renewed, scheduled change, canceled, expired, successful payment | Yes, through the webhook |
| Whether customers can cancel on Recurly's account management page | No. Not checked yet |
| Email templates (trial ending, renewal reminders) | No: Recurly says these can only be set in its admin console. Not checked yet until Checkbox sees the emails |
| Hosted payment page terms and consent | No. Checkbox checks your checkout page in a real browser instead |
| Whether the Checkbox webhook is added | No. It shows once deliveries arrive |
Checkbox never treats a setting it can't read as passing. It shows Not checked yet until it has evidence.
Recurly's JSON webhooks carry only ids, so after checking a delivery Checkbox reads the subscription, its plan and account with your key to see the dates and amounts.
What to check
- Online cancellation. In Configuration → Hosted Pages Settings → Account Management Pages, select Enabled and Account Login, so customers can sign in and cancel. Link to it from your account page.
- Reminder emails. In Recurly's email templates, turn on Trial Ending (sent 3 days before the trial ends by default) and Term Renewal Reminder or Bill Date Reminder, with timing inside the windows from
checkNoticeSchedule. Make sure each plan with a trial has Send Trial Ending Emails? on. Forward one real email of each kind to your site's inbound address so Checkbox can check it, or let Notices send them. - Yearly reminder. Recurly's Annual Reminder goes out once a year from each subscription's start, monthly plans included.
- Checkout consent. Put the full renewal terms and a required, unchecked renewal-consent checkbox on your own page or Recurly.js checkout, above the pay button.
- Price changes. Recurly emails ramp-price changes, but not other price changes. A change scheduled for the same plan at a higher price is recorded as a price change, so Checkbox asks you to confirm the notice went out.
Rules written and maintained by the Checkbox team from the text of each law, each cited to its source. Automated checks, not legal advice.
Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). You remain solely responsible for your subscription program, and Checkbox takes on no legal liability for it (Terms). Checkbox is a System1 company; Trust center · Status. For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.