chargebee-python

chargebee (the chargebee-python library) is the official Python SDK for integrating with Chargebee, a subscription billing and revenue-management platform. It wraps the Chargebee REST API behind a typed client and resource models so you can manage customers, subscriptions, plans, invoices, payments, and more without hand-rolling HTTP calls.

The v3 client centers on a Chargebee client object configured with your site and API key, with built-in support for retries, configurable connect/read timeouts, idempotency keys, telemetry adapters, and an optional async HTTP client. Over a hundred resource models cover the full breadth of the Chargebee API surface.

What You Get

• A configurable Chargebee client keyed by site and API key
• Over 100 resource models mapping the Chargebee API surface (customers, subscriptions, plans, invoices, credit notes, and more)
• Built-in retry handling with configurable delays and connect/read timeouts
• Idempotency-key support and an optional async HTTP client for high-throughput integrations

Common Use Cases

• Creating and updating subscriptions and customers from a Python backend
• Generating and retrieving invoices, credit notes, and payment records
• Handling recurring-billing workflows such as plan changes, proration, and exports

Under The Hood

Architecture - The SDK is organized around a Chargebee dataclass in chargebee/main.py that holds an Environment (site, api_key, endpoint, timeouts, telemetry). HTTP is centralized in chargebee/http_request.py, which builds basic-auth requests, applies retries and timeouts, and dispatches through httpx (sync or async). Resource entities live under chargebee/models (100+ modules) alongside request/response and filter helpers, so each API call maps to a model plus a typed request object.

Tech Stack - Pure Python targeting 3.11+, using httpx for HTTP with SSL/CA-cert bundling, dataclasses for the client, and standard-library modules for auth and retry logic. It packages via setup.py/pyproject.toml with a VERSION file and a Makefile for build tasks.

Code Quality - The code favors explicit modules per resource and a single request path, keeping cross-cutting concerns (retries, idempotency, telemetry, timeouts) in one place. A tests/ suite covers http_request, models, responses, telemetry, and utilities. Naming is consistent and Pythonic, and error types are modeled explicitly (APIError, PaymentError, InvalidRequestError, and more).

API Design - Getting started is a two-line client construction (Chargebee(api_key, site)) followed by resource calls, with fluent configuration methods for timeouts and retry delays. The large generated model surface trades some conceptual weight for completeness, but the ergonomics for common billing operations are clean and the migration guide plus API reference keep the learning curve moderate.