Skip to main content

Chargebee

Chargebee Integration Guide

Overview

This guide explains how to connect Bridged with Chargebee to read subscription data, customer information, invoices, and payment history. The integration supports reading this data for activation, qualification, and nurture playbooks where billing context is needed.

Chargebee is a subscription management and recurring billing platform that provides a REST API for accessing customers, subscriptions, invoices, and payments .

Primary Use Case: Read Subscription & Billing Data

For Bridged's monetization and commercial integrations, the primary use case is reading subscription-related data, including:

Data Type

Use in Bridged

Customer data

Personalize outreach based on subscription status

Subscriptions

Identify active/paused/canceled subscribers for qualification

Invoices

Track billing history and payment amounts

Payments

Monitor successful/failed payment events

Prerequisites

Before starting, ensure you have:

  • A Chargebee account (test mode recommended for initial setup)

  • Your Site Name (subdomain from your Chargebee URL, e.g., your-company in https://your-company.chargebee.com)

  • Your API Key (full-access or read-only key)

Note: API keys have site-level context and cannot be restricted to specific entities . Once created, you cannot change a key's permissions; you must delete it and create a new one .

API Key Types

Chargebee offers three types of API keys :

Key Type

Access Level

Best for

Full-access key

Read + Write all data

Full integration requiring writes

Read-only key

Read-only access to all data

Bridged's primary use case (preferred)

Publishable key

Limited read-only for frontend

Client-side operations (not for server)

Recommendation: For Bridged's read-only use case, use a Read-only: All API key.

Step 1: Obtain Your API Key

  1. Log in to your Chargebee account

  2. Navigate to Settings → Configure Chargebee → API keys and webhooks → API keys

  3. Click + Add API key

  4. Select Read-only: All as the API key type

  5. Enter a name (e.g., Bridged Integration)

  6. Click Create key

  7. Copy the API key immediately — you won't be able to see it again

Step 2: Configure Bridged to Connect to Chargebee

  1. Log in to your Bridged dashboard

  2. Navigate to the Integrations section. If you do not see this section, contact support@bridged.media

  3. Click Chargebee → Connect Account

  4. Enter the following credentials:

Field

Description

Site Name

Your Chargebee subdomain (e.g., your-company from your-company.chargebee.com)

API Key

Your read-only API key

Environment

Test Mode or Live Mode

  1. Click Connect

API Request Example

To verify your connection:

bash

curl -X GET "https://your-company.chargebee.com/api/v2/subscriptions" \
  -u "YOUR_API_KEY:" \
  -H "Content-Type: application/json"

Note: Chargebee uses Basic Authentication with the API key as the username and no password .

Step 3: Configure Webhooks for Real-time Events (Optional)

Chargebee webhooks enable real-time notifications for subscription lifecycle events .

Step 3.1: Set Up Webhook Endpoint in Chargebee

  1. Navigate to Settings → Configure Chargebee → Webhooks

  2. Click Add Webhook

  3. Enter a name (e.g., Bridged Integration)

  4. Set the Webhook URL to: https://gateway.bridged.media/webhooks/chargebee

  5. (Optional) Configure Basic Authentication username and password

  6. Select events to send (see below)

  7. Click Create Webhook

Step 3.2: Available Webhook Events

Event

When it triggers

customer_created

New customer added

customer_changed

Customer details updated

subscription_created

New subscription started

subscription_changed

Subscription plan changed

subscription_renewed

Subscription renewed

subscription_cancelled

Subscription canceled

payment_succeeded

Successful payment

invoice_generated

New invoice created

Step 4: Reading Data via API

Chargebee's REST API supports GET requests for all read operations . Responses are in JSON format.

List Subscriptions

bash

GET /api/v2/subscriptions

Key parameters:

  • limit - Max records per page (default 10, max 100)

  • offset - Starting position for pagination

  • status[in] - Filter by status (e.g., active, cancelled)

List Customers

bash

GET /api/v2/customers

List Invoices

bash

GET /api/v2/invoices?customer_id={CUSTOMER_ID}

List Payments

bash

GET /api/v2/payments?customer_id={CUSTOMER_ID}

Get Subscription by ID

bash

GET /api/v2/subscriptions/{SUBSCRIPTION_ID}

Step 5: Configure Sync Settings

Setting

Options

Description

Data objects

Customers, Subscriptions, Invoices, Payments

Which billing data to read

Sync frequency

Hourly, Daily, Weekly

How often to refresh data

Sync method

API Direct, Webhooks, Both

Preferred data access method

Subscription status filter

Active, Cancelled, All

Filter by subscription state

Bulk sync limit: Each bulk operation is limited to 50 records per request.

Rate Limiting & Performance

Consideration

Details

Rate limits

Vary by plan; check your Chargebee dashboard

Pagination

Use limit (max 100) and offset parameters

Bulk operations

Maximum 50 records per request

Common Use Cases

Playbook

How Subscription Data Is Used

Activation

Read active subscribers to trigger renewal reminders via WhatsApp

Qualification Agent

Read subscription tier and payment history to prioritize high-value customers

Nurture & Conversion

Read failed payment events for dunning follow-up

Example Conversation Powered by Chargebee Data

When a customer asks "What's my subscription status?", Bridged:

  1. Reads customer's active subscription from Chargebee API

  2. Retrieves plan name and status

  3. Returns subscription information conversationally

Security & Permissions

  • Chargebee uses API Key authentication via HTTP Basic Auth (API key as username, no password)

  • Use Read-only keys for Bridged's primary use case

  • API keys cannot be modified after creation; delete and recreate to change permissions

  • Webhook endpoints can be secured with Basic Authentication

  • All API calls should be made over TLS 1.2+

  • Credentials are encrypted and never stored in plain text

Troubleshooting

Issue

Likely cause

Solution

Connection fails (401)

Invalid API key

Verify key was copied correctly; create new key if needed

No data returned

Wrong site name

Check Chargebee URL for your site subdomain

Webhook not received

Wrong URL or missing auth

Verify webhook URL and Basic Auth credentials

Rate limiting

Too many requests

Reduce sync frequency; use pagination

Permission errors

Wrong key type

Use Read-only or Full-access key, not Publishable key

Support

For integration support, contact your Bridged account manager or email support@bridged.media.

For Chargebee-specific questions: