Checkbox Docs

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

  1. 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" }'
  1. 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.
  2. 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 connectBillingPlatform with { "platform": "recurly", "credentials": { "apiKey": "…", "region": "us" } } (region is us or eu; it defaults to us).
  3. 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_setup in 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.
  4. 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-signature on 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

SettingRead from Recurly?
Plans: price per currency, billing intervalYes. 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-renewYes. Plans with auto-renew off aren't checked as subscriptions
Subscription counts by stateYes. Counts only, no customer data
Subscription events: new, trial ending, renewal reminders, renewed, scheduled change, canceled, expired, successful paymentYes, through the webhook
Whether customers can cancel on Recurly's account management pageNo. 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 consentNo. Checkbox checks your checkout page in a real browser instead
Whether the Checkbox webhook is addedNo. 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.