Chargebee Python Client Library

Warnings

• breaking Python 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.
  Fix: Upgrade 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.
• breaking Chargebee 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.
  Fix: Ensure 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.
• gotcha The 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.
  Fix: Refer 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.
• gotcha All 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.
  Fix: Store 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.

Install

• pip install chargebee Install latest version
• pip install 'chargebee>=3,<4' Install latest v3.x.x

Imports

• Chargebee

  from chargebee import Chargebee

• Resource Objects (e.g., Customer, Subscription)

  response = cb_client.Customer.create(...)

  While models might exist, interactions are primarily done via the configured `Chargebee` client object (e.g., `cb_client.Customer` for Customer operations).

Quickstart

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.")