Migration guide for v3

This guide outlines the necessary changes for migrating from chargebee-python v2.x to chargebee-python v3.x

What's new?

• Type Hinting: Introduced to enhance IDE autocompletion and provide more accurate suggestions during development.
• Chargebee Client: Support for multiple clients has been introduced.
• Data Type Support: Added support for int, float, bool, and enum data types.
• Enums: Global and resource-specific enums have been introduced.
• Filter Params: Filter parameters for list type of requests have been introduced.
• Response Classes: Each API endpoint now has a dedicated response class that defines the return type, replacing the previous approach of accessing a generic response object.

Breaking changes

• Python 3.11+ is required
• A Chargebee client instance must now be created to access API operations. Direct configuration of Chargebee is no longer supported.
• List-type responses are now accessible via the list entry to align with the API contract.
• Response from previous API calls must be passed as arguments for wait_for_export_completion() and wait_for_time_travel_completion().

Code samples

Configuring Chargebee

A Chargebee client instance must now be created to access API operations. Direct configuration of Chargebee is no longer supported.

Before:

import chargebee

chargebee.configure("api_key", "site")

After:

from chargebee import Chargebee

cb_client = Chargebee(api_key="api_key", site="site")

Making a request

Parameters can now be passed as keyword arguments rather than as an encoded string.

Before:

import chargebee

result = chargebee.Customer.create({
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@test.com",
    "locale": "fr-CA",
    "billing_address": {
        "first_name": "John",
        "last_name": "Doe",
        "line1": "PO Box 9999",
        "city": "Walnut",
        "state": "California",
        "zip": "91789",
        "country": "US"
    }
})

After:

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

---

Parsing list type response

List-type responses are now accessible via the list entry to align with the API contract.

Before:

import chargebee

entries = chargebee.Customer.list({
    "limit": "5"
})
for entry in entries:
    customer = entry.customer
    card = entry.card

After:

response = cb_client.Customer.list(
    cb_client.Customer.ListParams(
        limit=5
    )
)
for entry in response.list:
    customer = entry.customer
    card = entry.card

---

Using filter params

Before:

import chargebee

entries = chargebee.Customer.list({
    "id[in]": ["BTTwXzUQUst2s1cox", "BTTwXzUQUtkFC1d2Q"],
    "first_name[is]": "John",
    "last_name[starts_with]": "Doe"
})

After:

from chargebee import Filters

response = cb_client.Customer.list(
    cb_client.Customer.ListParams(
        id=Filters.StringFilter(
            IN=["BTTwXzUQUst2s1cox", "BTTwXzUQUtkFC1d2Q"]
        ),
        first_name=Filters.StringFilter(
            IS="John"
        ),
        last_name=Filters.StringFilter(
            STARTS_WITH="Doe"
        )
    )
)

---

Using custom fields

Before:

import chargebee

response = chargebee.Customer.create({
    "first_name": "John",
    "cf_host_url": "https://john.com"  # `cf_host_url` is a custom field in Customer object
})

After:

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

---

Parsing API responses

Before:

import chargebee

result = chargebee.Customer.create({
    "first_name": "John",
    "last_name": "Doe"
})
customer = result.customer
card = result.card
subscription = result.subscription  # spurious reference as there won't be any subscriotion object returned from create customers endpoint

After:

result = cb_client.Customer.create(
    cb_client.Customer.CreateParams(
        first_name="John",
        last_name="Doe"
    )
)
# result variable won't have any other response object other than responses specified in the API contract
customer = result.customer
card = result.card

---

Response headers

Before:

import chargebee

result = chargebee.Customer.list()
response_headers = result.get_response_headers

After:

response = cb_client.Customer.list()
response_headers = response.headers

---

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()

Before:

import chargebee

result = chargebee.Export.customers({
    "customer": {
        "first_name[is]": "John"
    }
})
print(chargebee.Export.wait_for_export_completion())

After:

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

---

Refer to the README for additional code samples.