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
, and504
. - Exponential backoff: Retry delays increase exponentially to prevent overwhelming the server.
- Rate limit management: If a
429 Too Many Requests
response is received with aRetry-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
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 |
a5c7a4c30b54bbdd3deb186edf7af67bc77277468d7c598db7a86a92deb616d0
|
|
MD5 |
f71295659224f02037103632dbed488f
|
|
BLAKE2b-256 |
4599d0894003e46e87830f47c594956ebe50a4ae4093043cd2df9d318c7b2ebc
|
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
Algorithm | Hash digest | |
---|---|---|
SHA256 |
3d3c273c892531367acce142598a257562f471c773b4f9c5e29c674a2e7ac501
|
|
MD5 |
8febb0571b4c5fb6ffe41291d01c3418
|
|
BLAKE2b-256 |
36755e7239de94662aa94e4bb32a19cb4090e049c721cec376cf83a79ce03171
|