v4.12.0

v4.12.0 (2026-06-30)

---

New Features

• Added an optional telemetryAdapter hook for tracing Chargebee API calls via OpenTelemetry (or any APM). Configure it once on the client (ChargebeeClient.Builder#telemetryAdapter) or per call (RequestOptions.Builder#telemetryAdapter). When unconfigured, the SDK skips all telemetry work — no behavior change for existing integrations.
• Each API call emits one CLIENT span (chargebee.{resource}.{operation}) with OpenTelemetry HTTP semantic-convention attributes (url.full, http.request.method, server.address, http.response.status_code) plus chargebee.* attributes. Adapters may inject W3C trace context (traceparent, tracestate) into outbound request headers for distributed tracing.
• Exposed the TelemetryAdapter, RequestTelemetryContext, RequestTelemetryResult, RequestTelemetryError types, the TelemetrySupport helpers, and the TelemetryAttributeKeys constants under com.chargebee.v4.telemetry.
• Added a convenience updateGift(String giftId) overload (and its updateGiftAsync async variant) to GiftService for invoking update_gift without params.

v4.11.0

v4.11.0 (2026-06-29)

---

Bug Fixes:

• Fixed JSON request body serialization where Timestamp parameters were sent in a human-readable format (e.g. "expires_at":"2026-06-23 09:54:44.513") instead of Unix seconds. They are now serialized as numeric Unix seconds (e.g. "expires_at":1782189229), matching the form-url-encoded path and the format expected by the API. This affects all JSON content-type endpoints, such as create_promotional_grant in PromotionalGrant.
• Fixed JSON request body serialization for endpoints that accept nested objects and arrays. Previously the JSON body reused the application/x-www-form-urlencoded flattening (e.g. events[deduplication_id][]) and double-encoded nested objects; the JSON content-type now emits a proper nested structure. This affects JSON endpoints such as ingest_usages_in_batch and create_a_usage_event in UsageEvent.
• Fixed usage_timestamp for UsageEvent to be sent as epoch milliseconds. The usage_timestamp parameter in create_a_usage_event and ingest_usages_in_batch is now typed as Long (epoch milliseconds) instead of Timestamp, preserving the millisecond precision required by the ingestion API.

v3.50.0

v3.50.0 (2026-06-22)

---

Bug Fixes:

• Fixed JSON request body serialization where Timestamp parameters were sent in a human-readable format (e.g. "expires_at":"2026-06-23 09:54:44.513") instead of Unix seconds. They are now serialized as numeric Unix seconds (e.g. "expires_at":1782189229), matching the form-url-encoded path and the format expected by the API. This affects all JSON content-type endpoints, such as create_promotional_grant in PromotionalGrant.

v4.10.0

v4.10.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.

v3.49.0

v3.49.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.

v4.9.0

v4.9.0 (2026-06-08)

New Attributes:

• purchased_at has been added to OmnichannelSubscription.
• updated_at has been added to OmnichannelSubscription.
• updated_at has been added to OmnichannelSubscriptionItem.

New Parameters:

• customer_id.in has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.
• customer_id.not_in has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.
• id has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.
• id_at_source has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.
• updated_at has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.
• purchased_at has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.
• gift_receiver has been added as request body parameter to update_a_gift in Gift.
• layout has been added as request body parameter to checkout_gift_subscription_for_items in HostedPage.

Parameter Updates:

• scheduled_at has been changed from required to optional in update_a_gift of Gift.

New Events:

• omnichannel_subscription_item_updated has been added.
• omnichannel_subscription_item_recovered has been added.

Deleted Resources:

• QuoteEntitlement has been removed.

Deleted Attributes:

• entity_id has been removed from QuoteEntitlement.
• entity_type has been removed from QuoteEntitlement.
• feature_id has been removed from QuoteEntitlement.
• value has been removed from QuoteEntitlement.
• is_enabled has been removed from QuoteEntitlement.
• start_date has been removed from QuoteEntitlement.
• end_date has been removed from QuoteEntitlement.
• created_at has been removed from QuoteEntitlement.
• modified_at has been removed from QuoteEntitlement.

Deleted Parameters:

• exclude has been removed as query parameter from list_invoices in Invoice.

New Enums:

• omnichannel_subscription_item_updated and omnichannel_subscription_item_recovered have been added as new values enum EventType.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values enum PaymentMethod.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values enum PaymentMethodType.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values enum Type.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values to enum attribute payment_method_type in PaymentIntent.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values to enum attribute active_payment_attempt.payment_method_type in PaymentIntent.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values to enum request body parameter payment_method_type in update_a_payment_intent of PaymentIntent.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values to enum request body parameter payment_method_type in create_a_payment_intent of PaymentIntent.

v3.48.0

v3.48.0 (2026-06-08)

New Attributes:

• purchased_at has been added to OmnichannelSubscription.
• updated_at has been added to OmnichannelSubscription.
• updated_at has been added to OmnichannelSubscriptionItem.

New Parameters:

• customer_id.in has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.
• customer_id.not_in has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.
• id has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.
• id_at_source has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.
• updated_at has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.
• purchased_at has been added as query parameter to list_omnichannel_subscriptions in OmnichannelSubscription.
• gift_receiver has been added as request body parameter to update_a_gift in Gift.
• layout has been added as request body parameter to checkout_gift_subscription_for_items in HostedPage.

Parameter Updates:

• scheduled_at has been changed from required to optional in update_a_gift of Gift.

New Events:

• omnichannel_subscription_item_updated has been added.
• omnichannel_subscription_item_recovered has been added.

Deleted Resources:

• QuoteEntitlement has been removed.

Deleted Attributes:

• entity_id has been removed from QuoteEntitlement.
• entity_type has been removed from QuoteEntitlement.
• feature_id has been removed from QuoteEntitlement.
• value has been removed from QuoteEntitlement.
• is_enabled has been removed from QuoteEntitlement.
• start_date has been removed from QuoteEntitlement.
• end_date has been removed from QuoteEntitlement.
• created_at has been removed from QuoteEntitlement.
• modified_at has been removed from QuoteEntitlement.

Deleted Parameters:

• exclude has been removed as query parameter from list_invoices in Invoice.

New Enums:

• omnichannel_subscription_item_updated and omnichannel_subscription_item_recovered have been added as new values enum EventType.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values enum PaymentMethod.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values enum PaymentMethodType.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values enum Type.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values to enum attribute payment_method_type in PaymentIntent.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values to enum attribute active_payment_attempt.payment_method_type in PaymentIntent.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values to enum request body parameter payment_method_type in update_a_payment_intent of PaymentIntent.
• klarna, alipay_hk, paypay, gcash, and south_korean_cards have been added as new values to enum request body parameter payment_method_type in create_a_payment_intent of PaymentIntent.

v4.8.0

v4.8.0 (2026-06-02)

---

Enhancements:

• Added a fromJson(Map<String, Object>) overload to all models, so nested map entities can be converted to a typed model directly (e.g. Subscription.fromJson(subscription)).

Bug Fixes:

• Fixed deserialization of nested JSON in dynamic Map<String, Object> fields (for example HostedPage.getContent() and HostedPage.getCheckoutInfo()). Nested objects and arrays are now returned as Map and List instead of JSON strings, which resolves ClassCastException when casting nested entities such as customer, subscription, and invoice to Map<String, Object>. The same parsing behavior applies to other map attributes including Event.getContent(), meta_data, and consent_fields. If your integration previously parsed nested map values as JSON strings, use the returned Map/List directly or branch on instanceof during upgrade.

v4.7.0

v4.7.0 (2026-05-04)

New Resources:

• QuoteEntitlement has been added.

New Actions:

• list_applicable_alerts_for_a_subscription has been added to Alert.
• retrieve_an_alert has been added to Alert.
• update_an_alert has been added to Alert.
• delete_an_alert has been added to Alert.
• list_alerts has been added to Alert.
• create_an_alert has been added to Alert.
• list_alert_statuses_for_a_subscription has been added to AlertStatus.
• list_alert_statuses_for_an_alert has been added to AlertStatus.

New Attributes:

• alarm_status has been added to AlertStatus.

New Parameters:

• limit has been added as query parameter to list_applicable_alerts_for_a_subscription in Alert.
• offset has been added as query parameter to list_applicable_alerts_for_a_subscription in Alert.
• status has been added as query parameter to list_applicable_alerts_for_a_subscription in Alert.
• type has been added as query parameter to list_applicable_alerts_for_a_subscription in Alert.
• limit has been added as query parameter to list_alerts in Alert.
• offset has been added as query parameter to list_alerts in Alert.
• id has been added as query parameter to list_alerts in Alert.
• type has been added as query parameter to list_alerts in Alert.
• subscription_id has been added as query parameter to list_alerts in Alert.
• status has been added as query parameter to list_alerts in Alert.
• limit has been added as query parameter to list_alert_statuses_for_a_subscription in AlertStatus.
• offset has been added as query parameter to list_alert_statuses_for_a_subscription in AlertStatus.
• alarm_status has been added as query parameter to list_alert_statuses_for_a_subscription in AlertStatus.
• alert_id has been added as query parameter to list_alert_statuses_for_a_subscription in AlertStatus.
• limit has been added as query parameter to list_alert_statuses_for_an_alert in AlertStatus.
• offset has been added as query parameter to list_alert_statuses_for_an_alert in AlertStatus.
• alarm_status has been added as query parameter to list_alert_statuses_for_an_alert in AlertStatus.
• exclude has been added as query parameter to list_invoices in Invoice.
• threshold has been added as request body parameter to update_an_alert in Alert.
• status has been added as request body parameter to update_an_alert in Alert.
• threshold has been added as request body parameter to create_an_alert in Alert.
• filter_conditions has been added as request body parameter to create_an_alert in Alert.
• type has been added as request body parameter to create_an_alert in Alert.
• name has been added as request body parameter to create_an_alert in Alert.
• description has been added as request body parameter to create_an_alert in Alert.
• metered_feature_id has been added as request body parameter to create_an_alert in Alert.
• subscription_id has been added as request body parameter to [create_an_alert](https://apidocs.chargebee.com/docs/ap...

v3.47.0

v3.47.0 (2026-05-04)

New Resources:

• QuoteEntitlement has been added.

New Actions:

• list_applicable_alerts_for_a_subscription has been added to Alert.
• retrieve_an_alert has been added to Alert.
• update_an_alert has been added to Alert.
• delete_an_alert has been added to Alert.
• list_alerts has been added to Alert.
• create_an_alert has been added to Alert.
• list_alert_statuses_for_a_subscription has been added to AlertStatus.
• list_alert_statuses_for_an_alert has been added to AlertStatus.

New Attributes:

• alarm_status has been added to AlertStatus.

New Parameters:

• limit has been added as query parameter to list_applicable_alerts_for_a_subscription in Alert.
• offset has been added as query parameter to list_applicable_alerts_for_a_subscription in Alert.
• status has been added as query parameter to list_applicable_alerts_for_a_subscription in Alert.
• type has been added as query parameter to list_applicable_alerts_for_a_subscription in Alert.
• limit has been added as query parameter to list_alerts in Alert.
• offset has been added as query parameter to list_alerts in Alert.
• id has been added as query parameter to list_alerts in Alert.
• type has been added as query parameter to list_alerts in Alert.
• subscription_id has been added as query parameter to list_alerts in Alert.
• status has been added as query parameter to list_alerts in Alert.
• limit has been added as query parameter to list_alert_statuses_for_a_subscription in AlertStatus.
• offset has been added as query parameter to list_alert_statuses_for_a_subscription in AlertStatus.
• alarm_status has been added as query parameter to list_alert_statuses_for_a_subscription in AlertStatus.
• alert_id has been added as query parameter to list_alert_statuses_for_a_subscription in AlertStatus.
• limit has been added as query parameter to list_alert_statuses_for_an_alert in AlertStatus.
• offset has been added as query parameter to list_alert_statuses_for_an_alert in AlertStatus.
• alarm_status has been added as query parameter to list_alert_statuses_for_an_alert in AlertStatus.
• exclude has been added as query parameter to list_invoices in Invoice.
• threshold has been added as request body parameter to update_an_alert in Alert.
• status has been added as request body parameter to update_an_alert in Alert.
• threshold has been added as request body parameter to create_an_alert in Alert.
• filter_conditions has been added as request body parameter to create_an_alert in Alert.
• type has been added as request body parameter to create_an_alert in Alert.
• name has been added as request body parameter to create_an_alert in Alert.
• description has been added as request body parameter to create_an_alert in Alert.
• metered_feature_id has been added as request body parameter to create_an_alert in Alert.
• subscription_id has been added as request body parameter to [create_an_alert](https://apidocs.chargebee.com/docs/a...