Chargebee

Chargebee

Subscription billing and revenue management platform. Manages the full lifecycle: catalog → subscribe → invoice → collect → report. Each customer site is a named Chargebee site configured on the connection.

Entity Hierarchy

Product Catalog (Items model)

• Item Families — top-level grouping (e.g. "Cloud Plans", "Add-ons").
• Items — individual products/services within a family. Each item has an id used across the system.
• Item Prices — specific pricing variants of an item (monthly, annual, per-unit, tiered). Linked to items by item_id.
• Attached Items — items bundled together (e.g. mandatory add-ons). Queried by parent item_id.
• Differential Prices — customer-specific or plan-specific price overrides.

Legacy Catalog (Plans model)

• Plans — pricing templates (legacy). Being replaced by Items model.
• Addons — optional extras attached to plans (legacy).

Billing

• Customers — billable entities with contact info, billing address, payment methods.
• Contacts — additional people on a customer account. Fetched by customer id.
• Subscriptions — recurring agreements linking a customer to item prices. Status: active, in_trial, cancelled, non_renewing, paused.
• Scheduled Changes — pending modifications to a subscription (e.g. plan change at renewal). Queried by subscription_id.
• Invoices — generated from subscription activity. Contains line items, taxes, discounts.
• Credit Notes — refund/adjustment records linked to invoices.
• Unbilled Charges — charges accrued but not yet invoiced.
• Transactions — payment/refund records.
• Payment Sources — stored payment methods (cards, bank accounts).
• Virtual Bank Accounts — for ACH/wire payments.

Promotions

• Coupons — discount codes with redemption limits and applicability rules.
• Promotional Credits — account credits applied to future invoices.
• Gifts — subscription gifting records.

Operations

• Quotes — pre-invoice proposals. Quote Line Groups break down a quote's pricing (queried by quote_id).
• Orders — fulfillment records for physical goods.
• Comments — internal notes on any entity.
• Events — webhook event log (audit trail of all changes).
• Hosted Pages — checkout/portal page sessions.
• Site Migration Details — for site-to-site data migration tracking.

Workflows

1. Subscription audit: Enumerate subscriptions, read statuses and scheduled changes, then pull recent invoices for the same accounts.
2. Revenue snapshot: Walk customers, subscriptions, transactions, and credit notes to reconstruct cash movement.
3. Catalog review: Traverse item families, salable items, price rows, and bundled attachments to understand the matrix.
4. Customer deep-dive: Locate the customer, load contacts, subscriptions, and invoices in that order.
5. Discount analysis: Review coupons and promotional credits, then relate them back to the subscriptions consuming them.

Gotchas

• Response envelope: List responses nest each record under its entity key (customer, subscription, etc.) inside the list array.
• Pagination: Offset-based—read next_offset (or equivalent) from the response to continue.
• Dependent lookups: Attached items need a parent item id; quote line groups need a quote id; scheduled subscription changes need a subscription id; ancillary contacts need a customer id—gather parents first.
• Subscription statuses matter: cancelled subs may still have current_term_end in the future (end-of-term cancellation). non_renewing means active but won't auto-renew.
• Items vs Plans: Chargebee supports both the newer Items model and legacy Plans model—expect either (or both) depending on how the site was provisioned.