# Chargebee

> Connect a Chargebee site with a read-only API key so Checkbox reads your plans, trials and subscription events, and see what it can't read from Chargebee.

> **Checks only.** Checkbox checks your pages, emails and cancellation flow, and reads your Chargebee plans and
> subscription events. Checkbox never changes anything in Chargebee. 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 Chargebee API with a read-only key, and turns Chargebee webhooks
(new subscriptions, trial-ending and renewal reminders, renewals, plan 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: "chargebee"`:

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

2. Create a read-only API key in Chargebee: **Settings → Configure Chargebee → API Keys and Webhooks → API Keys →
   Add API Key → Read-Only Key**. Choose **All**, or **Restricted** with both **Product catalog** and **Transactional
   data** checked. The direct link is `https://{your-site}.chargebee.com/apikeys_and_webhooks/api`. Test and live sites
   have different keys: use the key of the site you want checked.
3. In the dashboard, open **Site → Settings → Billing connection**, choose Chargebee, and enter your **site name** (the
   `acme` of `acme.chargebee.com`) and the key. Checkbox reads your plans once to check the key, then stores it
   encrypted. With the API, call `connectBillingPlatform` with
   `{ "platform": "chargebee", "credentials": { "site": "acme", "apiKey": "…" } }`.
4. Add the webhook. Chargebee doesn't sign webhooks, so each site gets its own username and password. After you
   connect, the dashboard shows the webhook URL, username, password and events (they're also under **Billing connection
   → Chargebee webhook**, and in `webhook_setup` in the API response). In Chargebee, open **Settings → Configure
   Chargebee → API Keys and Webhooks → Webhooks → Add Webhook**, paste the URL, turn on **Protect webhook URL with
   basic authentication**, enter the username and password, choose API version **v2**, and select the events (or keep
   All Events).

## What Checkbox reads {#reads}

| Setting | Read from Chargebee? |
|---|---|
| Plans: price, billing period, currency | Yes. Product Catalog 2.0 item prices or Product Catalog 1.0 plans, whichever your site uses. Tiered plans are read at their first-tier price |
| Free trials (length, and whether the trial cancels instead of converting) | Yes, from each plan |
| Fixed-term plans (a set number of billing cycles) | Yes |
| Subscription events: created, trial ending, renewal reminder, renewed, changed, cancelled, payment succeeded | Yes, through the webhook |
| Whether customers can cancel in the Chargebee portal | Only when a subscriber cancelled there in the last 30 days. Otherwise **Not checked yet** |
| Email notifications (trial-ending and renewal reminders) | No. **Not checked yet** until Checkbox sees the emails (BCC them, below) |
| Checkout terms and consent checkbox | No. Checkbox checks your checkout page in a real browser instead |

Checkbox never treats a setting it can't read as passing. It shows **Not checked yet** until it has evidence.

## What to check {#what-to-check}

- **Portal cancellation.** In **Settings → Configure Chargebee → Checkout & Self-Serve Portal → Portal**, turn on
  **Allow customers to cancel subscription**, and link to the portal from your account page.
- **Reminder emails.** In **Settings → Configure Chargebee → Email Notifications**, turn on the trial-ending and renewal
  reminders and set the days so they fall inside the windows from
  [`checkNoticeSchedule`](https://checkbox.site/docs/api/checks#checkNoticeSchedule). Add your site's inbound address as BCC on the master
  template so Checkbox sees every send. Or let [Notices](https://checkbox.site/docs/guides/emails-and-notices) send them.
- **Checkout consent.** In **Settings → Configure Chargebee → Checkout & Self-Serve Portal → Checkout → Show legal
  information**, turn on **Show checkbox to get consent** and use renewal-consent wording. Put the full renewal terms on
  your own page above the button that opens Chargebee checkout.
- **Price changes.** Chargebee doesn't email price changes. A change you make to a subscription's recurring items is
  recorded as a possible 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.
