Skip to main content

Python wrapper for the Chargebee Subscription Billing API

Project description

Chargebee Python Client Library v3

This is the official Python library for integrating with Chargebee.

  • 📘 For a complete reference of available APIs, check out our API Documentation.
  • 🧪 To explore and test API capabilities interactively, head over to our API Explorer.

If you're upgrading from an older version please refer to the Migration Guide

Requirements

  • Python 3.11+

Installation

Install the latest version of the library with pip:

pip install chargebee

Install from source with:

python setup.py install

Documentation

See our Python API Reference.

Usage

The package needs to be configured with your site's API key, which is available under Configure Chargebee Section. Refer here for more details.

Configuring chargebee client

from chargebee import Chargebee
cb_client = Chargebee(api_key="", site="")

Configuring Timeouts

from chargebee import Chargebee
cb_client = Chargebee(api_key="api_key", site="site")
cb_client.update_read_timeout_secs(3000)
cb_client.update_connect_timeout_secs(5000)

Configuring Retry Delays

from chargebee import Chargebee
cb_client = Chargebee(api_key="api_key", site="site")
cb_client.update_export_retry_delay_ms(3000)
cb_client.update_time_travel_retry_delay_ms(5000)

Making API Request:

# Create a Customer

response = cb_client.Customer.create(
    cb_client.Customer.CreateParams(
        first_name="John",
        last_name="Doe",
        email="john@test.com",
        locale="fr-CA",
        billing_address=cb_client.Customer.BillingAddress(
            first_name="John",
            last_name=" Doe",
            line1="PO Box 9999",
            city="Walnut",
            state="California",
            zip="91789",
            country="US",
        ),
    )
)
customer = response.customer
card = response.card

List API Request With Filter

For pagination, offset is the parameter that is being used. The value used for this parameter must be the value returned in next_offset parameter from the previous API call.

from chargebee import Filters

response = cb_client.Customer.list(
    cb_client.Customer.ListParams(
        first_name=Filters.StringFilter(IS="John")
    )
)
offset = response.next_offset
print(offset)

Using enums

There are two variants of enums in chargebee,

  • Global enums - These are defined globally and can be accessed across resources.
  • Resource specific enums - These are defined within a resource and can be accessed using the resource class name.
# Global Enum
import chargebee

response = cb_client.Customer.create(
    cb_client.Customer.CreateParams(
        first_name="John",
        auto_collection=chargebee.AutoCollection.ON,  # global enum
    )
)
print(response.customer)
# Resource Specific Enum

response = cb_client.Customer.change_billing_date(
    cb_client.Customer.ChangeBillingDateParams(
        first_name="John",
        billing_day_of_week=cb_client.Customer.BillingDayOfWeek.MONDAY,  # resource specific enum
    )
)
print(response.customer)

Using custom fields

response = cb_client.Customer.create(
    cb_client.Customer.CreateParams(
        first_name="John",
        cf_host_url="https://john.com",  # `cf_host_url` is a custom field in Customer object
    )
)
print(response.customer.cf_host_url)

Creating an idempotent request:

Idempotency keys are passed along with request headers to allow a safe retry of POST requests.

response = cb_client.Customer.create(
    cb_client.Customer.CreateParams(
        first_name="John",
        last_name="Doe",
        email="john@test.com",
        locale="fr-CA",
        billing_address=cb_client.Customer.BillingAddress(
            first_name="John",
            last_name=" Doe",
            line1="PO Box 9999",
            city="Walnut",
            state="California",
            zip="91789",
            country="US",
        ),
    ),
    None,
    {
        "chargebee-idempotency-key": "<<UUID>>"
    },  # Replace <<UUID>> with a unique string
)
customer = response.customer
card = response.card
responseHeaders = response.headers  # Retrieves response headers
print(responseHeaders)
idempotencyReplayedValue = response.is_idempotency_replayed  # Retrieves Idempotency replayed header value
print(idempotencyReplayedValue)

Waiting for Process Completion

The response from the previous API call must be passed as an argument for wait_for_export_completion() or wait_for_time_travel_completion()

# Wait For Export Completion

from chargebee import Filters

response = cb_client.Export.customers(
    cb_client.Export.CustomersParams(
        customer=cb_client.Export.CustomersCustomerParams(
            first_name=Filters.StringFilter(IS="John")
        )
    )
)
print(cb_client.Export.wait_for_export_completion(response.export))

Retry Handling

Chargebee's SDK includes built-in retry logic to handle temporary network issues and server-side errors. This feature is disabled by default but can be enabled when needed.

Key features include:

  • Automatic retries for specific HTTP status codes: Retries are automatically triggered for status codes 500, 502, 503, and 504.
  • Exponential backoff: Retry delays increase exponentially to prevent overwhelming the server.
  • Rate limit management: If a 429 Too Many Requests response is received with a Retry-After header, the SDK waits for the specified duration before retrying.

    Note: Exponential backoff and max retries do not apply in this case.

  • Customizable retry behavior: Retry logic can be configured using the retryConfig parameter in the environment configuration.

Example: Customizing Retry Logic

You can enable and configure the retry logic by passing a retryConfig object when initializing the Chargebee environment:

from chargebee import Chargebee
from chargebee.retry_config import RetryConfig

retry_config = RetryConfig(
    enabled=True,
    max_retries=5,
    delay_ms=1000,
    retry_on=[500]
)
cb_client = Chargebee(api_key="api_key", site="site")
cb_client.update_retry_config(retry_config)

# ... your Chargebee API operations ...

Example: Rate Limit retry logic

You can enable and configure the retry logic for rate-limit by passing a retryConfig object when initializing the Chargebee environment:

from chargebee import Chargebee
from chargebee.retry_config import RetryConfig

retry_config = RetryConfig(
    enabled=True,
    max_retries=5,
    delay_ms=1000,
    retry_on=[429]
)
cb_client = Chargebee(api_key="api_key", site="site")
cb_client.update_retry_config(retry_config)

# ... your Chargebee API operations ...

Feedback

If you find any bugs or have any feedback, open an issue in this repository or email it to dx@chargebee.com

License

See the LICENSE file.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chargebee-3.7.0.tar.gz (245.4 kB view details)

Uploaded Source

Built Distribution

chargebee-3.7.0-py3-none-any.whl (333.3 kB view details)

Uploaded Python 3

File details

Details for the file chargebee-3.7.0.tar.gz.

File metadata

  • Download URL: chargebee-3.7.0.tar.gz
  • Upload date:
  • Size: 245.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.3

File hashes

Hashes for chargebee-3.7.0.tar.gz
Algorithm Hash digest
SHA256 a5c7a4c30b54bbdd3deb186edf7af67bc77277468d7c598db7a86a92deb616d0
MD5 f71295659224f02037103632dbed488f
BLAKE2b-256 4599d0894003e46e87830f47c594956ebe50a4ae4093043cd2df9d318c7b2ebc

See more details on using hashes here.

File details

Details for the file chargebee-3.7.0-py3-none-any.whl.

File metadata

  • Download URL: chargebee-3.7.0-py3-none-any.whl
  • Upload date:
  • Size: 333.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.3

File hashes

Hashes for chargebee-3.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 3d3c273c892531367acce142598a257562f471c773b4f9c5e29c674a2e7ac501
MD5 8febb0571b4c5fb6ffe41291d01c3418
BLAKE2b-256 36755e7239de94662aa94e4bb32a19cb4090e049c721cec376cf83a79ce03171

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page