Release v3.24.0

[cb-alish]

v3.24.0 (2026-06-12)

New Resources:

• GrantBlock has been added.
• LedgerAccountBalance has been added.
• LedgerOperation has been added.
• PromotionalGrant has been added.

New Attributes:

• notes has been added to CreditNote.
• layout has been added to HostedPage.

New Parameters:

• sort_by has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.

New Enums:

• available, exhausted, scheduled, and in_grace_period have been added as new values enum Status.
• subscription_created, subscription_changed, top_up, promotional_grants, and rollover have been added as new values to enum attribute grant_source in GrantBlock.
• provisioned and overdraft have been added as new values to enum attribute account_type in GrantBlock.
• credit_unit has been added as a new value to enum attribute unit_type in GrantBlock.
• credit_unit has been added as a new value to enum attribute unit_type in LedgerAccountBalance.
• allocation, capture, authorize, release_authorization, capture_authorization, expiry, void, rollover, and adjustment have been added as new values to enum attribute type in LedgerOperation.
• credit_unit has been added as a new value to enum attribute unit_type in LedgerOperation.
• expires_at, created_at, and effective_from have been added as new values to enum query parameter sort_by.asc in list_grant_blocks of GrantBlock.
• expires_at, created_at, and effective_from have been added as new values to enum query parameter sort_by.desc in list_grant_blocks of GrantBlock.
• allocation, release_authorization, void, capture, rollover, adjustment, expiry, authorize, and capture_authorization have been added as new values to enum query parameter type.is in list_ledger_operations of LedgerOperation.
• allocation, release_authorization, void, capture, rollover, adjustment, expiry, authorize, and capture_authorization have been added as new values to enum query parameter type.in in list_ledger_operations of LedgerOperation.
• created_at has been added as a new value to enum query parameter sort_by.asc in list_ledger_operations of LedgerOperation.
• created_at has been added as a new value to enum query parameter sort_by.desc in list_ledger_operations of LedgerOperation.
• updated_at and created_at have been added as new values to enum query parameter sort_by.asc in list_omnichannel_subscriptions of OmnichannelSubscription.
• updated_at and created_at have been added as new values to enum query parameter sort_by.desc in list_omnichannel_subscriptions of OmnichannelSubscription.

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[hivel-marco]

PR Complexity Score: 5.1 - Moderate

View Breakdown

• Lines Changed: 585
• Files Changed: 22
• Complexity Added: 16
• Raw Score: 101.7

Overview

This PR releases version 3.24.0 of the SDK, introducing new credit-based resources and operations to support grant blocks, ledger balances/operations, and promotional grants. It adds new attributes, enums, and sorting/filtering parameters across several existing resources, and wires the new models into the main client. It also slightly adjusts hosted page behavior and omnichannel subscription listing capabilities.

Key Changes

• Bumps library version from 3.23.0 to 3.24.0 and documents the release in the changelog, including all new resources, attributes, parameters, and enum values.
• Introduces the GrantBlock resource, with list support (list_grant_blocks), new enums for grant source/account type/unit type, and associated response models, including status tracking and metadata.
• Adds the LedgerAccountBalance resource, enabling listing of balances per subscription/unit, including separate provisioned and overdraft balance structures.
• Adds the LedgerOperation resource, supporting retrieval, listing with filtering/sorting, and new write operations (capture, authorize, capture_authorization, release_authorization), along with detailed ledger operation response models and idempotency handling.
• Introduces the PromotionalGrant resource with a promotional_grants operation to create promotional grants that return related ledger operations and grant blocks, with idempotent behavior.
• Adds a generic Status enum and wires it into the shared models package for use with new grant-related flows.
• Extends CreditNoteResponse to include a notes field and HostedPageResponse to include a layout attribute, improving response completeness.
• Enhances OmnichannelSubscription listing by adding a sort_by parameter that supports sorting by created_at and updated_at.
• Removes the UPDATE_PAYMENT_METHOD value from the HostedPage.Type enum, changing the set of valid hosted page types.
• Registers all new resources (GrantBlock, LedgerAccountBalance, LedgerOperation, PromotionalGrant) on the main chargebee client so they are directly accessible from the SDK entrypoint.

Risks & Considerations

• Removal of HostedPage.Type.UPDATE_PAYMENT_METHOD is a potential breaking change for any callers referencing this enum value; reviewers should confirm this aligns with API deprecation plans.
• New credit/grant-related resources (GrantBlock, LedgerAccountBalance, LedgerOperation, PromotionalGrant) must match the live API contracts (field names, types, and required parameters); any divergence could cause runtime errors or mis-typed responses.
• The new sorting and filtering options (e.g., sort_by on omnichannel subscriptions, grant blocks, and ledger operations) rely on backend support for the new fields (created_at, updated_at, expires_at, effective_from); reviewers should verify the backend supports these combinations.
• The new Status enum name is quite generic; reviewers should ensure it does not conflict conceptually or semantically with any existing status enums in the SDK.
• Idempotency handling in the promotional_grants, capture, authorize, capture_authorization, and release_authorization calls should be validated against server-side expectations, particularly around is_idempotency_replayed semantics and metadata serialization.
• None identified.

File-level change summary

File	Change summary
CHANGELOG.md	Adds v3.24.0 release notes describing new resources, attributes, parameters, and enum values.
VERSION	Updates the library version string from 3.23.0 to 3.24.0.
chargebee/main.py	Registers new client entrypoints for GrantBlock, LedgerAccountBalance, LedgerOperation, and PromotionalGrant.
chargebee/models/init.py	Exposes the new Status enum and wires in the new grant/ledger/promotional_grant model operation classes.
chargebee/models/credit_note/responses.py	Adds a notes: List[str] field to CreditNoteResponse.
chargebee/models/enums.py	Introduces a new Status enum with values available, exhausted, scheduled, and in_grace_period.
chargebee/models/grant_block/init.py	Exposes GrantBlock operations and GrantBlockResponse from the grant_block package.
chargebee/models/grant_block/operations.py	Implements the GrantBlock client with enums and the list_grant_blocks API including filtering and sorting parameters.
chargebee/models/grant_block/responses.py	Defines response dataclasses for grant blocks and for listing grant blocks with pagination.
chargebee/models/hosted_page/operations.py	Removes the UPDATE_PAYMENT_METHOD member from the HostedPage.Type enum.
chargebee/models/hosted_page/responses.py	Adds a layout field to HostedPageResponse.
chargebee/models/ledger_account_balance/init.py	Exposes LedgerAccountBalance operations and LedgerAccountBalanceResponse.
chargebee/models/ledger_account_balance/operations.py	Implements LedgerAccountBalance list API, unit type enum, and typed structures for provisioned and overdraft balances.
chargebee/models/ledger_account_balance/responses.py	Adds response models for provisioned/overdraft balances and for listing ledger account balances.
chargebee/models/ledger_operation/init.py	Exposes LedgerOperation operations and LedgerOperationResponse.
chargebee/models/ledger_operation/operations.py	Implements LedgerOperation APIs for retrieve, list, capture, authorize, capture_authorization, and release_authorization with filtering/sorting.
chargebee/models/ledger_operation/responses.py	Defines LedgerOperation response models including idempotent responses that also return updated ledger account balances.
chargebee/models/omnichannel_subscription/operations.py	Extends list parameters for omnichannel subscriptions to include a sort_by filter.
chargebee/models/promotional_grant/init.py	Exposes PromotionalGrant operations and PromotionalGrantResponse.
chargebee/models/promotional_grant/operations.py	Adds the PromotionalGrant client with a promotional_grants POST API supporting metadata and idempotency.
chargebee/models/promotional_grant/responses.py	Defines promotional grant response models including returned ledger operations and grant blocks.
chargebee/version.py	Updates the SDK version constant to 3.24.0.

[hivel-marco]

PR Complexity Score: 2.9 - Simple

View Breakdown

• Lines Changed: 297
• Files Changed: 4
• Complexity Added: 14
• Raw Score: 38.94

Overview

This PR adds new client operations for managing credit-based ledger entities (grant blocks, ledger account balances, and ledger operations) and adjusts an existing offer fulfillment request.
It introduces typed parameter structures and enums for these new endpoints, aligning them with the existing Chargebee request/response patterns.
Additionally, it changes the behavior of the offer_fulfillments_get API call by altering a request option flag.

Key Changes

• Introduces GrantBlock operations with typed filtering parameters and enums for grant source, account type, and unit type, plus a list_grant_blocks method to retrieve grant blocks by subscription and filters.
• Adds LedgerAccountBalance operations including typed structures for provisioned and overdraft balances, along with a list_ledger_account_balances method filtered by subscription and unit.
• Adds LedgerOperation operations, including:
  • Enum for operation types (allocation, capture, authorize, rollover, adjustment, etc.) and unit type.
  • list_ledger_operations and retrieve_ledger_operation for querying operations.
  • Mutation endpoints: capture, authorize, capture_authorization, and release_authorization, with typed parameter objects and support for metadata.
• Updates offer_fulfillments_get to call request.send with the grow flag set to False instead of True, changing how response growth/expansion is handled for that endpoint.

Risks & Considerations

• Newly introduced endpoints depend on accurate backend support for grant_blocks, ledger_account_balances, and ledger_operations paths; any mismatch in path or schema may surface as runtime API errors.
• The change of grow from True to False in offer_fulfillments_get may alter the shape or completeness of returned data (e.g., fewer expanded objects), potentially affecting existing consumers that rely on expanded responses.
• TypedDict requirements (e.g., mandatory subscription_id, unit_id, timestamps) may cause breaking changes if existing internal call sites don’t provide these fields or if types don’t align with server expectations.
• Metadata is treated as JSON for ledger operation mutations; incorrect structures or large payloads could cause request failures or performance issues.

File-level change summary

File	Change summary
chargebee/models/grant_block/operations.py	Adds GrantBlock class with enums and list_grant_blocks operation to query grant blocks with filter support.
chargebee/models/ledger_account_balance/operations.py	Adds LedgerAccountBalance class with balance TypedDicts and list_ledger_account_balances query operation.
chargebee/models/ledger_operation/operations.py	Adds LedgerOperation class defining operation types and CRUD-style methods for listing, retrieving, and mutating ledger operations (capture/authorize flows).
chargebee/models/offer_fulfillment/operations.py	Changes offer_fulfillments_get to invoke request.send with the grow flag set to False instead of True.