> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chargebee Integration

> Sync revenue data from Chargebee to power segments and automations

Connect your Chargebee site to automatically sync revenue metrics for all your subscribers. This enables powerful segmentation based on MRR and LTV, plus automations triggered by every billing event.

## What is Chargebee?

[Chargebee](https://www.chargebee.com) is a subscription billing and revenue management platform. It handles plans, trials, invoicing, dunning, and payments across multiple gateways, and is widely used by SaaS and subscription businesses.

## Connecting Chargebee

Chargebee requires an API key and webhook setup. Here's how to connect:

### Step 1: Get Your Chargebee API Key

1. Go to your Chargebee dashboard (`https://your-site.chargebee.com`)
2. Navigate to **Settings → Configure Chargebee → API Keys**
3. Create a key (a **read-only key** is sufficient) and copy it

### Step 2: Find Your Site Name

Your site name is the subdomain of your Chargebee dashboard URL. If your dashboard lives at `acme.chargebee.com`, your site name is `acme` (test sites usually end in `-test`, e.g. `acme-test`).

### Step 3: Set Up Webhooks in Chargebee

1. In Chargebee, go to **Settings → Configure Chargebee → Webhooks**
2. Click **Add Webhook**
3. Enter your Sequenzy webhook URL:
   ```
   https://api.sequenzy.com/api/webhooks/chargebee/{your-company-id}
   ```
   <Note>
     You can find this URL in Sequenzy when connecting Chargebee - it's
     automatically shown in the connection modal.
   </Note>
4. Enable **basic authentication** on the webhook and choose a username and password
5. Chargebee sends all events by default, so no per-event selection is needed. The events Sequenzy acts on include:
   * `payment_succeeded`
   * `payment_failed`
   * `payment_refunded`
   * `subscription_created`
   * `subscription_activated`
   * `subscription_cancellation_scheduled`
   * `subscription_cancelled`
   * `subscription_paused`
   * `subscription_resumed`
   * `subscription_reactivated`
   * `subscription_deleted`
   * `subscription_trial_end_reminder`
6. Save the webhook

### Step 4: Connect in Sequenzy

1. Go to **Settings → Integrations** in Sequenzy
2. Click **Connect** next to Chargebee
3. Enter your:
   * **Site Name** (from Step 2)
   * **API Key** (from Step 1)
   * **Webhook Username and Password** (the same credentials from Step 3)
4. Click **Connect Chargebee**

Sequenzy will immediately run an initial sync of your Chargebee customers, subscriptions, and paid invoices, and begin receiving webhook events.

<Warning>
  Webhook requests are authenticated with the basic auth credentials you
  entered. Requests without matching credentials are rejected, so make sure
  the username and password in Chargebee exactly match the ones entered in
  Sequenzy.
</Warning>

## Initial Sync

When you connect (or click **Sync Revenue** later), Sequenzy imports your full Chargebee history:

* **Customers** become subscribers, matched or created by email
* **Subscriptions** determine status tags and MRR
* **Paid invoices** are summed into each customer's LTV

The sync is idempotent - running it again updates existing subscribers instead of creating duplicates.

## Synced Attributes

When connected, Sequenzy adds these attributes to each subscriber matched by email:

| Attribute             | Type   | Description                                                                 |
| --------------------- | ------ | --------------------------------------------------------------------------- |
| `mrr`                 | Number | Monthly Recurring Revenue in dollars (normalized from any billing interval) |
| `ltv`                 | Number | Lifetime Value - total payments minus refunds                               |
| `chargebeeCustomerId` | String | The customer's ID in Chargebee                                              |

### MRR Calculation

MRR is normalized from any billing interval:

* **Monthly**: Used as-is (divided by the billing period for multi-month plans)
* **Yearly**: Divided by 12
* **Weekly**: Multiplied by 52, then divided by 12
* **Daily**: Multiplied by 365, then divided by 12

Only `active` and `in_trial` subscriptions count toward MRR. Both Product Catalog 1.0 (`plan_amount`) and 2.0 (`subscription_items`) sites are supported, and non-USD currencies are converted automatically.

## Automatic Tags

Sequenzy automatically applies tags to subscribers based on their Chargebee subscription status:

| Tag            | Applied When                              |
| -------------- | ----------------------------------------- |
| `customer`     | Has an active subscription                |
| `trial`        | Has a subscription in trial               |
| `cancelled`    | Subscription is scheduled to cancel       |
| `churned`      | Subscription has been cancelled or paused |
| `saas.monthly` | On a monthly billing interval             |
| `saas.yearly`  | On a yearly billing interval              |

These tags update automatically whenever subscription status changes via webhooks.

## Tracked Events

When you connect Chargebee, these events are automatically tracked for use in automations:

| Event                   | Triggered When                                           |
| ----------------------- | -------------------------------------------------------- |
| `saas.purchase`         | Payment received (new subscription, renewal, or upgrade) |
| `saas.purchase_monthly` | Payment for a monthly subscription                       |
| `saas.purchase_yearly`  | Payment for a yearly subscription                        |
| `saas.payment_failed`   | Payment attempt failed                                   |
| `saas.trial_started`    | Subscription created in trial                            |
| `saas.trial_will_end`   | Chargebee's trial-ending reminder fired                  |
| `saas.trial_ended`      | Trial converted to an active subscription                |
| `saas.trial_cancelled`  | Subscription cancelled before ever activating            |
| `saas.cancelled`        | Cancellation scheduled for the end of the billing term   |
| `saas.churn`            | Subscription cancelled, deleted, or paused               |
| `saas.refund`           | Payment refunded                                         |

## Idempotency and Retries

Every Chargebee event has a unique ID. Sequenzy records processed event IDs per subscriber, so duplicate webhook deliveries and Chargebee's automatic retries never double-count MRR or LTV. Failed event processing returns a success acknowledgment to avoid retry storms, and the periodic **Sync Revenue** action reconciles any missed events from the API.

## Using Revenue Data

### Building Segments

With MRR and LTV synced as numeric attributes, you can create sophisticated segments:

**Revenue-based segments:**

* `mrr >= 100` - High MRR customers
* `ltv > 1000` - Lifetime high-value customers
* `mrr >= 50 AND mrr < 200` - Mid-tier customers

**Combining with tags:**

* `tag = churned AND ltv > 500` - High-value churned customers (win-back targets)
* `tag = cancelled AND mrr >= 100` - At-risk high-value customers needing attention
* `tag = trial` - Everyone currently trialing, for conversion campaigns

### Automations

Trigger automations from Chargebee billing events:

* Start an onboarding sequence on `saas.trial_started`
* Send conversion nudges on `saas.trial_will_end`
* Trigger dunning emails on `saas.payment_failed`
* Launch a win-back sequence when a subscriber gets the `churned` tag

## How Matching Works

Subscribers are matched by email address (case-insensitive). A Chargebee customer with email `User@Example.com` will match a subscriber with email `user@example.com`.

If a Chargebee customer doesn't have an email in the webhook or doesn't match any subscriber, the event is acknowledged but no action is taken.

## Troubleshooting

### Webhooks Not Arriving

1. Verify your webhook URL is correct in Chargebee settings
2. Check Chargebee's webhook logs (**Settings → Configure Chargebee → Webhooks**) for failed delivery attempts
3. Ensure basic authentication is enabled on the webhook

### Webhook Authentication Failing

If webhooks are rejected with authentication errors:

1. Verify the username and password in Chargebee match what you entered in Sequenzy exactly
2. Reconnect the integration in Sequenzy to update the stored credentials

### Sync Fails or Shows an Error

1. Verify the API key is valid and hasn't been revoked in Chargebee
2. Confirm the site name matches your Chargebee subdomain (including `-test` for test sites)
3. Check the integration's status in **Settings → Integrations** for the specific error message