Chargebee Integration

Chargebee is a subscription billing and revenue management platform that supports multiple payment gateways. LostChurn connects to Chargebee via API key and processes webhook events to add Smart Retry Engine and dunning capabilities on top of Chargebee's existing payment recovery features.

Prerequisites

• An active Chargebee account (any plan)
• Access to your Chargebee Dashboard with admin permissions
• A Chargebee Full Access or Custom API key
• A LostChurn account with at least one workspace created

Connection Steps

1. In the Chargebee Dashboard, navigate to Settings > Configure Chargebee > API Keys.
2. Click Add API Key.
3. Name the key LostChurn and select Full Access or create a custom role with the following permissions:
   • Subscriptions: Read and Write
   • Customers: Read
   • Invoices: Read and Write
   • Transactions: Read
   • Payment Sources: Read
   • Events: Read
4. Click Create Key and copy the generated API key.
5. Note your Chargebee site name (the subdomain of your-site.chargebee.com).
6. In your LostChurn dashboard, go to Settings > Integrations and click Connect Chargebee.
7. Enter your Chargebee site name and paste the API key.
8. Click Save and Verify. LostChurn makes a test API call to confirm the credentials are valid.

Webhook Configuration

1. In the Chargebee Dashboard, go to Settings > Configure Chargebee > Webhooks.
2. Click Add Webhook.
3. Set the Webhook URL to:

   https://webhooks.lostchurn.com/v1/chargebee

4. Under Event Types, select the following:
   • payment_failed
   • payment_succeeded
   • payment_refunded
   • subscription_cancelled
   • subscription_changed
   • subscription_renewed
   • subscription_reactivated
   • subscription_paused
   • subscription_resumed
   • subscription_renewal_reminder
   • invoice_generated
   • invoice_updated
   • invoice_deleted
   • card_expired
   • card_updated
   • card_expiry_reminder
   • payment_source_added
   • payment_source_updated
   • payment_source_deleted
5. Set the API Version to V2 (recommended).
6. Click Create.
7. Chargebee provides a Webhook Key (also referred to as the API key or password) for verifying payloads. Copy this key.
8. In your LostChurn dashboard, paste the webhook key into the Webhook Secret field on the Chargebee integration page.

Webhook Authentication

Chargebee secures webhook delivery using HTTP Basic Authentication. Chargebee sends the webhook key as the username in the Authorization: Basic header (with an empty password). LostChurn verifies this credential on every incoming request using a timing-safe comparison.

Verify Connection

1. In the Chargebee Dashboard, go to Settings > Configure Chargebee > Webhooks and select the LostChurn webhook.
2. Click Test Webhook. Chargebee sends a sample event to the endpoint.
3. In your LostChurn dashboard, navigate to Events and confirm the test event appears.
4. For a more realistic test, create a test subscription in your Chargebee test site using Chargebee's test card number 4012888888881881 (which simulates a decline on renewal).

A successful connection shows a green Connected badge on the Chargebee card in Settings > Integrations.

Supported Events

Provider-Specific Notes

Chargebee's Smart Dunning

Chargebee offers a built-in Smart Dunning feature that uses machine learning to optimize retry timing. When integrating LostChurn with Chargebee, consider the following approaches:

1. Replace Chargebee's dunning: Disable Chargebee's Smart Dunning under Settings > Configure Chargebee > Retry Settings and let LostChurn handle all retry scheduling and customer communications. This is recommended if you want unified recovery management across multiple payment processors.
2. Complement Chargebee's dunning: Keep Chargebee's retry logic active but use LostChurn for additional recovery channels (email personalization, SMS, in-app messages) and advanced analytics. Configure LostChurn to skip retry actions and focus on dunning communications only.

Test Sites

Chargebee provides test sites (ending in -test) that operate independently from production. All API calls and webhooks from test sites are sandboxed. LostChurn automatically detects test site connections and labels events accordingly.

Multi-Gateway Support

Chargebee supports connecting multiple payment gateways (Stripe, Braintree, Adyen, etc.) under a single Chargebee site. When LostChurn connects to Chargebee, it receives events from all configured gateways through Chargebee's unified webhook system. If you also have a direct integration with one of these gateways in LostChurn, deduplication logic ensures events are not processed twice.

Offline Payments

Chargebee supports offline payment methods (bank transfers, checks). LostChurn skips automatic retry for offline payment failures but can still trigger dunning emails reminding customers to complete their offline payment.

API Rate Limits

Chargebee enforces rate limits based on your plan:

• Launch/Rise: 150 requests per minute
• Scale: 300 requests per minute
• Enterprise: Custom limits

LostChurn monitors the X-RateLimit-Remaining header from Chargebee responses and throttles requests accordingly. If you consistently approach your rate limit, consider upgrading your Chargebee plan or contacting LostChurn support to optimize request batching.