chargebee 3.21.0 → 3.22.0

package/CHANGELOG.md

@@ -1,3 +1,39 @@
+### v3.22.0 (2026-03-02)
+* * *
+### New Resources:
+- [`UsageCharge`](https://apidocs.chargebee.com/docs/api/usage_charges) has been added.
+- [`UsageSummary`](https://apidocs.chargebee.com/docs/api/usage_summaries) has been added.
+
+
+### New Attributes:
+- [`free_period`](https://apidocs.chargebee.com/docs/api/quoted_subscriptions/quoted-subscription-object#free_period) has been added to [`QuotedSubscription`](https://apidocs.chargebee.com/docs/api/quoted_subscriptions).
+- [`free_period_unit`](https://apidocs.chargebee.com/docs/api/quoted_subscriptions/quoted-subscription-object#free_period_unit) has been added to [`QuotedSubscription`](https://apidocs.chargebee.com/docs/api/quoted_subscriptions).
+
+
+### New Parameters:
+- [`net_term_days`](https://apidocs.chargebee.com/docs/api/invoices/create-invoice-for-items-and-one-time-charges#net_term_days) has been added as request body parameter to [`create_invoice_for_items_and_one-time_charges`](https://apidocs.chargebee.com/docs/api/invoices/create-invoice-for-items-and-one-time-charges) in [`Invoice`](https://apidocs.chargebee.com/docs/api/invoices).
+- [`contract_term`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions/create-pricing-page-for-existing-subscription#contract_term) has been added as request body parameter to [`create_pricing_page_for_existing_subscription`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions/create-pricing-page-for-existing-subscription) in [`PricingPageSession`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions).
+- [`contract_term`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions/create-pricing-page-for-new-subscription#contract_term) has been added as request body parameter to [`create_pricing_page_for_new_subscription`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions/create-pricing-page-for-new-subscription) in [`PricingPageSession`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions).
+- [`subscription.free_period`](https://apidocs.chargebee.com/docs/api/quotes/create-a-quote-for-a-new-subscription-items#subscription_free_period) has been added as request body parameter to [`create_a_quote_for_a_new_subscription_items`](https://apidocs.chargebee.com/docs/api/quotes/create-a-quote-for-a-new-subscription-items) in [`Quote`](https://apidocs.chargebee.com/docs/api/quotes).
+- [`subscription.free_period_unit`](https://apidocs.chargebee.com/docs/api/quotes/create-a-quote-for-a-new-subscription-items#subscription_free_period_unit) has been added as request body parameter to [`create_a_quote_for_a_new_subscription_items`](https://apidocs.chargebee.com/docs/api/quotes/create-a-quote-for-a-new-subscription-items) in [`Quote`](https://apidocs.chargebee.com/docs/api/quotes).
+- [`subscription.free_period`](https://apidocs.chargebee.com/docs/api/quotes/edit-create-subscription-quote-for-items#subscription_free_period) has been added as request body parameter to [`edit_create_subscription_quote_for_items`](https://apidocs.chargebee.com/docs/api/quotes/edit-create-subscription-quote-for-items) in [`Quote`](https://apidocs.chargebee.com/docs/api/quotes).
+- [`subscription.free_period_unit`](https://apidocs.chargebee.com/docs/api/quotes/edit-create-subscription-quote-for-items#subscription_free_period_unit) has been added as request body parameter to [`edit_create_subscription_quote_for_items`](https://apidocs.chargebee.com/docs/api/quotes/edit-create-subscription-quote-for-items) in [`Quote`](https://apidocs.chargebee.com/docs/api/quotes).
+
+
+### New Enums:
+- `month`, `week`, `day`, `hour`, and `minute` have been added as new values enum `WindowSize`.
+- `cancel`, `renew_once`, `renew`, and `evergreen` have been added as new values to enum request body parameter `contract_term.action_at_term_end` in [`create_pricing_page_for_existing_subscription`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions/create-pricing-page-for-existing-subscription) of [`PricingPageSession`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions).
+- `cancel`, `renew_once`, `renew`, and `evergreen` have been added as new values to enum request body parameter `contract_term.action_at_term_end` in [`create_pricing_page_for_new_subscription`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions/create-pricing-page-for-new-subscription) of [`PricingPageSession`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions).
+
+
+
+### v3.21.1 (2026-02-20)
+* * * 
+
+### Core Changes: 
+
+- Added new core utility method. 
+
 ### v3.21.0 (2026-02-11)
 * * * 
 

package/README.md

@@ -20,6 +20,16 @@ If you're upgrading from an older version of [`chargebee-typescript`](https://ww
 
 Node.js 18 or higher.
 
+## Runtime Support
+
+This SDK supports multiple JavaScript runtimes:
+
+- **Node.js** 18+
+- **Deno**
+- **Bun**
+- **Cloudflare Workers**
+- **Edge Runtimes** (e.g., Vercel Edge, Netlify Edge Functions)
+
 ## Installation
 
 Install the library with npm:
@@ -37,6 +47,16 @@ With yarn:
 yarn add chargebee
 ```
 
+With bun:
+```sh
+bun add chargebee
+```
+
+With deno:
+```sh
+deno add npm:chargebee
+```
+
 ## Usage
 
 The package needs to be configured with your site's API key, which is available under Configure Chargebee Section. Refer [here](https://www.chargebee.com/docs/2.0/api_keys.html) for more details.
@@ -63,6 +83,34 @@ const chargebee = new Chargebee({
 });
 ```
 
+### Using Deno:
+
+```typescript
+import Chargebee from "npm:chargebee";
+
+const chargebee = new Chargebee({
+  site: "{{site}}",
+  apiKey: "{{api-key}}",
+});
+
+const response = await chargebee.customer.list();
+console.log(response);
+```
+
+### Using Bun:
+
+```typescript
+import Chargebee from "chargebee";
+
+const chargebee = new Chargebee({
+  site: "{{site}}",
+  apiKey: "{{api-key}}",
+});
+
+const response = await chargebee.customer.list();
+console.log(response);
+```
+
 ### Using Async / Await
 
 ```typescript
@@ -159,6 +207,7 @@ The simplest way to handle webhooks is using the `webhooks` property on your ini
 ```typescript
 import express from 'express';
 import Chargebee, {
+  WebhookEventType,
   AuthenticationError,
   PayloadValidationError,
   PayloadParseError,
@@ -173,7 +222,7 @@ const app = express();
 app.use(express.json());
 
 // ⚠️ Register listeners once at startup, not inside request handlers
-chargebee.webhooks.on('subscription_created', async ({ event, response }) => {
+chargebee.webhooks.on(WebhookEventType.SubscriptionCreated, async ({ event, response }) => {
   console.log(`Subscription created: ${event.id}`);
   const subscription = event.content.subscription;
   console.log(`Customer: ${subscription.customer_id}`);
@@ -217,6 +266,7 @@ For more control or multiple webhook endpoints, use `chargebee.webhooks.createHa
 ```typescript
 import express, { Request, Response } from 'express';
 import Chargebee, {
+  WebhookEventType,
   basicAuthValidator,
   AuthenticationError,
   PayloadValidationError,
@@ -240,7 +290,7 @@ handler.requestValidator = basicAuthValidator((username, password) => {
 });
 
 // ⚠️ Register event listeners once at startup, not inside request handlers
-handler.on('subscription_created', async ({ event, response }) => {
+handler.on(WebhookEventType.SubscriptionCreated, async ({ event, response }) => {
   console.log(`Subscription created: ${event.id}`);
   const subscription = event.content.subscription;
   console.log(`Customer: ${subscription.customer_id}`);
@@ -248,7 +298,7 @@ handler.on('subscription_created', async ({ event, response }) => {
   response?.status(200).send('OK');
 });
 
-handler.on('payment_succeeded', async ({ event, response }) => {
+handler.on(WebhookEventType.PaymentSucceeded, async ({ event, response }) => {
   console.log(`Payment succeeded: ${event.id}`);
   const transaction = event.content.transaction;
   const customer = event.content.customer;
@@ -285,7 +335,7 @@ For more control, you can parse webhook events manually:
 
 ```typescript
 import express from 'express';
-import Chargebee, { type WebhookEvent } from 'chargebee';
+import Chargebee, { type WebhookEvent, WebhookEventType } from 'chargebee';
 
 const app = express();
 app.use(express.json());
@@ -293,23 +343,27 @@ app.use(express.json());
 app.post('/chargebee/webhooks', async (req, res) => {
   try {
     const event = req.body as WebhookEvent;
-    
+
     switch (event.event_type) {
-      case 'subscription_created':
-        // Access event content with proper typing
-        const subscription = event.content.subscription;
+      case WebhookEventType.SubscriptionCreated: {
+        // Cast to specific event type for proper content typing
+        const typedEvent = event as WebhookEvent<WebhookEventType.SubscriptionCreated>;
+        const subscription = typedEvent.content.subscription;
         console.log('Subscription created:', subscription.id);
         break;
-        
-      case 'payment_succeeded':
-        const transaction = event.content.transaction;
+      }
+
+      case WebhookEventType.PaymentSucceeded: {
+        const typedEvent = event as WebhookEvent<WebhookEventType.PaymentSucceeded>;
+        const transaction = typedEvent.content.transaction;
         console.log('Payment succeeded:', transaction.amount);
         break;
-        
+      }
+
       default:
         console.log('Unhandled event type:', event.event_type);
     }
-    
+
     res.status(200).send('OK');
   } catch (err) {
     console.error('Error processing webhook:', err);
@@ -327,7 +381,7 @@ app.listen(8080);
 **Respond with 200** to acknowledge receipt:
 
 ```typescript
-handler.on('subscription_created', async ({ event, response }) => {
+handler.on(WebhookEventType.SubscriptionCreated, async ({ event, response }) => {
   await provisionAccess(event.content.subscription);
   response?.status(200).json({ received: true });
 });
@@ -336,7 +390,7 @@ handler.on('subscription_created', async ({ event, response }) => {
 **Respond with 5xx** so Chargebee retries on failure:
 
 ```typescript
-handler.on('payment_succeeded', async ({ event, response }) => {
+handler.on(WebhookEventType.PaymentSucceeded, async ({ event, response }) => {
   try {
     await recordPayment(event.content.transaction);
     response?.status(200).send('OK');
@@ -349,7 +403,7 @@ handler.on('payment_succeeded', async ({ event, response }) => {
 **Access request context** (headers, middleware data):
 
 ```typescript
-handler.on('customer_created', async ({ event, request, response }) => {
+handler.on(WebhookEventType.CustomerCreated, async ({ event, request, response }) => {
   const tenantId = (request as any)?.tenant?.id;
   await createCustomerForTenant(tenantId, event.content.customer);
   response?.status(200).send('OK');

package/cjs/createChargebee.js

@@ -18,6 +18,9 @@ const CreateChargebee = (httpClient) => {
         this._endpoints = api_endpoints_js_1.Endpoints;
         // Initialize webhooks handler with auto-configured Basic Auth (if env vars are set)
         const handler = (0, handler_js_1.createDefaultHandler)();
+        this.__clientIdentifier = (serviceName) => {
+            (0, util_js_1.extend)(true, this._env, { userAgentSuffix: serviceName });
+        };
         // Create webhooks namespace with handler methods + createHandler factory
         this.webhooks = Object.assign(handler, {
             createHandler(options) {

package/cjs/environment.js

@@ -11,7 +11,7 @@ exports.Environment = {
     hostSuffix: '.chargebee.com',
     apiPath: '/api/v2',
     timeout: DEFAULT_TIME_OUT,
-    clientVersion: 'v3.21.0',
+    clientVersion: 'v3.22.0',
     port: DEFAULT_PORT,
     timemachineWaitInMillis: DEFAULT_TIME_MACHINE_WAIT,
     exportWaitInMillis: DEFAULT_EXPORT_WAIT,

package/cjs/resources/api_endpoints.js

@@ -4872,6 +4872,32 @@ exports.Endpoints = {
         ],
         ['list', 'GET', '/webhook_endpoints', null, false, null, false, {}, {}],
     ],
+    usageSummary: [
+        [
+            'retrieveUsageSummaryForSubscription',
+            'GET',
+            '/subscriptions',
+            '/usage_summary',
+            true,
+            null,
+            false,
+            {},
+            {},
+        ],
+    ],
+    usageCharge: [
+        [
+            'retrieveUsageChargesForSubscription',
+            'GET',
+            '/subscriptions',
+            '/usage_charges',
+            true,
+            null,
+            false,
+            {},
+            {},
+        ],
+    ],
     impactedCustomer: [],
     subscriptionEntitlementsUpdatedDetail: [],
     subscriptionEntitlementsCreatedDetail: [],

package/esm/createChargebee.js

@@ -15,6 +15,9 @@ export const CreateChargebee = (httpClient) => {
         this._endpoints = Endpoints;
         // Initialize webhooks handler with auto-configured Basic Auth (if env vars are set)
         const handler = createDefaultHandler();
+        this.__clientIdentifier = (serviceName) => {
+            extend(true, this._env, { userAgentSuffix: serviceName });
+        };
         // Create webhooks namespace with handler methods + createHandler factory
         this.webhooks = Object.assign(handler, {
             createHandler(options) {

package/esm/environment.js

@@ -8,7 +8,7 @@ export const Environment = {
     hostSuffix: '.chargebee.com',
     apiPath: '/api/v2',
     timeout: DEFAULT_TIME_OUT,
-    clientVersion: 'v3.21.0',
+    clientVersion: 'v3.22.0',
     port: DEFAULT_PORT,
     timemachineWaitInMillis: DEFAULT_TIME_MACHINE_WAIT,
     exportWaitInMillis: DEFAULT_EXPORT_WAIT,

package/esm/resources/api_endpoints.js

@@ -4869,6 +4869,32 @@ export const Endpoints = {
         ],
         ['list', 'GET', '/webhook_endpoints', null, false, null, false, {}, {}],
     ],
+    usageSummary: [
+        [
+            'retrieveUsageSummaryForSubscription',
+            'GET',
+            '/subscriptions',
+            '/usage_summary',
+            true,
+            null,
+            false,
+            {},
+            {},
+        ],
+    ],
+    usageCharge: [
+        [
+            'retrieveUsageChargesForSubscription',
+            'GET',
+            '/subscriptions',
+            '/usage_charges',
+            true,
+            null,
+            false,
+            {},
+            {},
+        ],
+    ],
     impactedCustomer: [],
     subscriptionEntitlementsUpdatedDetail: [],
     subscriptionEntitlementsCreatedDetail: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chargebee",
-  "version": "3.21.0",
+  "version": "3.22.0",
   "description": "A library for integrating with Chargebee.",
   "scripts": {
     "prepack": "npm install && npm run build",

package/types/core.d.ts

@@ -670,5 +670,6 @@ declare module 'chargebee' {
     | 'partially_valid'
     | 'invalid';
   type VoucherTypeEnum = 'boleto';
+  type WindowSizeEnum = 'month' | 'week' | 'day' | 'hour' | 'minute';
   type ChargeOnEnum = 'immediately' | 'on_event';
 }

package/types/index.d.ts

@@ -94,8 +94,10 @@
 ///<reference path='./resources/Transaction.d.ts' />
 ///<reference path='./resources/UnbilledCharge.d.ts' />
 ///<reference path='./resources/Usage.d.ts' />
+///<reference path='./resources/UsageCharge.d.ts' />
 ///<reference path='./resources/UsageEvent.d.ts' />
 ///<reference path='./resources/UsageFile.d.ts' />
+///<reference path='./resources/UsageSummary.d.ts' />
 ///<reference path='./resources/VirtualBankAccount.d.ts' />
 ///<reference path='./resources/WebhookEndpoint.d.ts' />
 ///<reference path='./resources/Content.d.ts' />
@@ -238,8 +240,10 @@ declare module 'chargebee' {
     transaction: Transaction.TransactionResource;
     unbilledCharge: UnbilledCharge.UnbilledChargeResource;
     usage: Usage.UsageResource;
+    usageCharge: UsageCharge.UsageChargeResource;
     usageEvent: UsageEvent.UsageEventResource;
     usageFile: UsageFile.UsageFileResource;
+    usageSummary: UsageSummary.UsageSummaryResource;
     virtualBankAccount: VirtualBankAccount.VirtualBankAccountResource;
     webhookEndpoint: WebhookEndpoint.WebhookEndpointResource;
 

package/types/resources/Content.d.ts

@@ -99,8 +99,10 @@ declare module 'chargebee' {
     transaction: Transaction;
     unbilled_charge: UnbilledCharge;
     usage: Usage;
+    usage_charge: UsageCharge;
     usage_event: UsageEvent;
     usage_file: UsageFile;
+    usage_summary: UsageSummary;
     virtual_bank_account: VirtualBankAccount;
     webhook_endpoint: WebhookEndpoint;
   }

package/types/resources/Invoice.d.ts

@@ -907,6 +907,7 @@ declare module 'chargebee' {
       authorization_transaction_id?: string;
       payment_source_id?: string;
       auto_collection?: AutoCollectionEnum;
+      net_term_days?: number;
       invoice_date?: number;
       token_id?: string;
       replace_primary_payment_source?: boolean;

package/types/resources/ItemEntitlement.d.ts

@@ -52,11 +52,11 @@ declare module 'chargebee' {
     }
 
     export interface AddItemEntitlementsResponse {
-      item_entitlement: ItemEntitlement;
+      list: { item_entitlement: ItemEntitlement }[];
     }
 
     export interface UpsertOrRemoveItemEntitlementsForItemResponse {
-      item_entitlement: ItemEntitlement;
+      list: { item_entitlement: ItemEntitlement }[];
     }
 
     // REQUEST PARAMS

package/types/resources/PricingPageSession.d.ts

@@ -43,6 +43,7 @@ declare module 'chargebee' {
       customer?: CustomerCreateForNewSubscriptionInputParam;
       billing_address?: BillingAddressCreateForNewSubscriptionInputParam;
       shipping_address?: ShippingAddressCreateForNewSubscriptionInputParam;
+      contract_term?: ContractTermCreateForNewSubscriptionInputParam;
       discounts?: DiscountsCreateForNewSubscriptionInputParam[];
     }
     export interface CreateForExistingSubscriptionInputParam {
@@ -50,6 +51,7 @@ declare module 'chargebee' {
       custom?: any;
       pricing_page?: PricingPageCreateForExistingSubscriptionInputParam;
       subscription?: SubscriptionCreateForExistingSubscriptionInputParam;
+      contract_term?: ContractTermCreateForExistingSubscriptionInputParam;
       discounts?: DiscountsCreateForExistingSubscriptionInputParam[];
     }
     export interface BillingAddressCreateForNewSubscriptionInputParam {
@@ -96,6 +98,10 @@ declare module 'chargebee' {
       country?: string;
       validation_status?: ValidationStatusEnum;
     }
+    export interface ContractTermCreateForNewSubscriptionInputParam {
+      action_at_term_end?: 'renew' | 'evergreen' | 'cancel' | 'renew_once';
+      cancellation_cutoff_period?: number;
+    }
     export interface SubscriptionCreateForNewSubscriptionInputParam {
       id?: string;
     }
@@ -115,6 +121,10 @@ declare module 'chargebee' {
     export interface PricingPageCreateForExistingSubscriptionInputParam {
       id?: string;
     }
+    export interface ContractTermCreateForExistingSubscriptionInputParam {
+      action_at_term_end?: 'renew' | 'evergreen' | 'cancel' | 'renew_once';
+      cancellation_cutoff_period?: number;
+    }
     export interface SubscriptionCreateForExistingSubscriptionInputParam {
       id: string;
     }

package/types/resources/Quote.d.ts

@@ -1120,6 +1120,8 @@ declare module 'chargebee' {
       start_date?: number;
       offline_payment_method?: OfflinePaymentMethodEnum;
       contract_term_billing_cycle_on_renewal?: number;
+      free_period?: number;
+      free_period_unit?: FreePeriodUnitEnum;
     }
 
     export interface SubscriptionItemsCreateSubItemsForCustomerQuoteInputParam {
@@ -1219,6 +1221,8 @@ declare module 'chargebee' {
       start_date?: number;
       offline_payment_method?: OfflinePaymentMethodEnum;
       contract_term_billing_cycle_on_renewal?: number;
+      free_period?: number;
+      free_period_unit?: FreePeriodUnitEnum;
     }
 
     export interface SubscriptionItemsEditCreateSubCustomerQuoteForItemsInputParam {

package/types/resources/QuotedSubscription.d.ts

@@ -19,6 +19,8 @@ declare module 'chargebee' {
     plan_unit_price_in_decimal?: string;
     changes_scheduled_at?: number;
     change_option?: 'end_of_term' | 'specific_date' | 'immediately';
+    free_period?: number;
+    free_period_unit?: FreePeriodUnitEnum;
     contract_term_billing_cycle_on_renewal?: number;
     addons?: QuotedSubscription.Addon[];
     event_based_addons?: QuotedSubscription.EventBasedAddon[];

package/types/resources/UsageCharge.d.ts

@@ -0,0 +1,47 @@
+///<reference path='./../core.d.ts'/>
+///<reference path='./../index.d.ts'/>
+///<reference path='./filter.d.ts'/>
+declare module 'chargebee' {
+  export interface UsageCharge {
+    subscription_id: string;
+    feature_id: string;
+    included_usage?: string;
+    total_usage?: string;
+    on_demand_usage?: string;
+    metered_item_price_id?: string;
+    amount?: string;
+    currency_code?: string;
+    usage_from: number;
+    usage_to: number;
+  }
+
+  export namespace UsageCharge {
+    export class UsageChargeResource {
+      /**
+       * @deprecated This method is deprecated and will be removed in a future version.
+       */
+
+      retrieveUsageChargesForSubscription(
+        subscription_id: string,
+        input?: RetrieveUsageChargesForSubscriptionInputParam,
+        headers?: ChargebeeRequestHeader,
+      ): Promise<
+        ChargebeeResponse<RetrieveUsageChargesForSubscriptionResponse>
+      >;
+    }
+
+    export interface RetrieveUsageChargesForSubscriptionResponse {
+      list: { usage_charge: UsageCharge }[];
+      next_offset?: string;
+    }
+
+    // REQUEST PARAMS
+    //---------------
+
+    export interface RetrieveUsageChargesForSubscriptionInputParam {
+      limit?: number;
+      offset?: string;
+      feature_id?: filter.String;
+    }
+  }
+}

package/types/resources/UsageSummary.d.ts

@@ -0,0 +1,45 @@
+///<reference path='./../core.d.ts'/>
+///<reference path='./../index.d.ts'/>
+///<reference path='./filter.d.ts'/>
+declare module 'chargebee' {
+  export interface UsageSummary {
+    subscription_id: string;
+    feature_id: string;
+    aggregated_value: string;
+    aggregated_from: number;
+    aggregated_to: number;
+  }
+
+  export namespace UsageSummary {
+    export class UsageSummaryResource {
+      /**
+       * @deprecated This method is deprecated and will be removed in a future version.
+       */
+
+      retrieveUsageSummaryForSubscription(
+        subscription_id: string,
+        input: RetrieveUsageSummaryForSubscriptionInputParam,
+        headers?: ChargebeeRequestHeader,
+      ): Promise<
+        ChargebeeResponse<RetrieveUsageSummaryForSubscriptionResponse>
+      >;
+    }
+
+    export interface RetrieveUsageSummaryForSubscriptionResponse {
+      list: { usage_summary: UsageSummary }[];
+      next_offset?: string;
+    }
+
+    // REQUEST PARAMS
+    //---------------
+
+    export interface RetrieveUsageSummaryForSubscriptionInputParam {
+      limit?: number;
+      offset?: string;
+      feature_id: string;
+      window_size?: 'month' | 'week' | 'day' | 'hour' | 'minute';
+      timeframe_start?: number;
+      timeframe_end?: number;
+    }
+  }
+}