# 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](https://checkbox.site/docs/guides/test-runs#generic). 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](https://checkbox.site/docs/guides/emails-and-notices).

## Connect {#connect}

1. Register the site with `platform: "recurly"`:

```curl
curl https://app.checkbox.site/v1/sites \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://acme-saas.example", "platform": "recurly" }'
```
```node
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);
```
```python
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"])
```

2. 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.
3. 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`).
4. 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.
5. 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 {#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 {#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 {#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`](https://checkbox.site/docs/api/checks#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](https://checkbox.site/docs/guides/emails-and-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.
