Chargebee Integration

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 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}
   
   You can find this URL in Sequenzy when connecting Chargebee - it’s automatically shown in the connection modal.
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.

​

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:

​

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: 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:

​

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