Install & Compatibility
Where this runs
tested against v2.60.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Chargebee
✓ from chargebee import Chargebee
Resource Objects (e.g., Customer, Subscription)
✓ response = cb_client.Customer.create(...)
✗ from chargebee.models import Customer
While models might exist, interactions are primarily done via the configured `Chargebee` client object (e.g., `cb_client.Customer` for Customer operations).
This quickstart demonstrates how to initialize the Chargebee client using environment variables for security and then perform a basic operation, such as creating a new customer. It highlights the use of `Chargebee.Customer.CreateParams` for structured request bodies. Ensure you replace placeholder values or set environment variables before running.
import os
from chargebee import Chargebee
# Configure the Chargebee client with your API key and site name
# It's recommended to use environment variables for sensitive data
API_KEY = os.environ.get('CHARGEBEE_API_KEY', 'your_test_api_key')
SITE_NAME = os.environ.get('CHARGEBEE_SITE_NAME', 'your_test_site')
if API_KEY == 'your_test_api_key' or SITE_NAME == 'your_test_site':
print("WARNING: Please set CHARGEBEE_API_KEY and CHARGEBEE_SITE_NAME environment variables.")
print("Using placeholder values, API calls will likely fail.")
cb_client = Chargebee(api_key=API_KEY, site=SITE_NAME)
try:
# Example: Create a new customer
# Note: CreateParams are nested under the resource class via the client
response = cb_client.Customer.create(
cb_client.Customer.CreateParams(
first_name="John",
last_name="Doe",
email="john.doe@example.com",
locale="en-US"
)
)
customer = response.customer
print(f"Successfully created customer: {customer.id} - {customer.email}")
# Example: Retrieve a customer
# response = cb_client.Customer.retrieve(customer.id)
# retrieved_customer = response.customer
# print(f"Retrieved customer: {retrieved_customer.id} - {retrieved_customer.first_name}")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure your API key and site name are correct and have appropriate permissions.")
Debug
Known issues
breakingPython Client Library v2 is deprecated and will no longer be supported after December 31, 2025. Users must migrate to v3.x.x to ensure continued support and access to new features.fixUpgrade your `chargebee` library to version `3.x.x` (e.g., `pip install 'chargebee>=3,<4'`). Review the official migration guide for changes between v2 and v3.
affects: <3.0.0
breakingChargebee will rotate TLS certificates with a permanent switch to DigiCert G2 chain by February 2026. Failure to update your environment's trust stores or ensure compatibility might cause API calls to fail with SSL errors.fixEnsure your operating system and Python environment's root certificate bundles are up-to-date. Consult Chargebee's official documentation for specific guidance on the TLS G2 certificate update.
affects: All versions if underlying system TLS is not updated.
gotchaThe Chargebee API has two major versions (v1 and v2), and the Python client library has its own versions (v2 and v3). The Python SDK v3 is compatible with the Chargebee API v2. It is crucial to ensure your SDK version is compatible with your Chargebee site's configured API version.fixRefer to the official Chargebee Python SDK README and API documentation for compatibility matrices between SDK versions and Chargebee API versions. Verify your site's API version in the Chargebee dashboard.
affects: All versions
gotchaAll API requests use HTTP Basic Auth where your API key is the username and the password field is left empty. API keys are environment-specific (test vs. live site) and must be kept secure. Do not expose them in client-side code or public repositories.fixStore API keys securely using environment variables or a secrets management service. Always use HTTPS for API communication. Use appropriate API keys for test and production environments.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'chargebee'
The 'chargebee' Python package is not installed in the active Python environment or there is a typo in the import statement.
fixInstall the library using pip: `pip install chargebee`.
chargebee.APIError: {'message': 'Sorry, authentication failed. Invalid API Key.', 'http_status_code': 401, ...}
The API key or site name provided during the Chargebee client initialization is incorrect or refers to a non-existent Chargebee site.
fixVerify your Chargebee API key and site name in your Chargebee dashboard (Settings > Configure Chargebee > API Keys) and ensure they are correctly passed to `chargebee.Chargebee(api_key="your_api_key", site="your_site_name")`.
AttributeError: module 'chargebee.Customer' has no attribute 'create_params'
This error often occurs when attempting to call API methods with incorrect parameter passing. In Chargebee Python Client Library v3, parameters for API calls like `create` are typically passed as instances of nested `CreateParams` classes, not as direct attributes or methods.
fixConsult the official Chargebee Python API reference for the specific API method. For `create` methods, parameters should be encapsulated within a `CreateParams` object, e.g., `cb_client.Customer.create(cb_client.Customer.CreateParams(first_name="John"))`.
chargebee.APIError: {'message': 'The value X is already present.', 'http_status_code': 400, 'api_error_code': 'duplicate_value', ...}
An attempt was made to create a Chargebee resource (e.g., a customer or subscription) with an ID or unique identifier that already exists in your Chargebee site.
fixEnsure that the unique identifiers (like customer ID, subscription ID, or email for certain configurations) provided in your API request are unique or correspond to an existing resource if you intend to update it. Validate input data before making the API call.
chargebee.APIError: {'message': 'Cannot find resource with id: X', 'http_status_code': 404, 'api_error_code': 'resource_not_found', ...}
The API request attempted to retrieve, update, or delete a resource (e.g., plan, customer, subscription) using an ID that does not exist in the specified Chargebee site.
fixVerify that the resource ID (e.g., `plan_id`, `customer_id`) used in your API call is correct and corresponds to an active resource in your Chargebee test or live site.
Upgrade
Version history
3.28.0latest on PyPI · released Aug 19, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.11 or newer.