chargebee 3.31.0 → 3.33.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+### v3.33.0 (2026-09-09)
+* * *
+### Bug Fixes
+* PC-V1 attributes (`plan_id`, `plan_quantity`, `plan_constraint`, `addon_constraint`, `embed`, etc.) are now typed as optional across all affected resources (`Subscription`, `Coupon`, `HostedPage`, `Quote`, `QuotedSubscription`, `Estimate`, `Gift`). PC-V1 and PC-V2 APIs coexist — these fields are absent in PC-V2 responses, so requiring them caused incorrect type errors for PC-V2 users.
+
+
+### v3.32.0 (2026-09-08)
+* * *
+### New Features
+* Added anonymous SDK telemetry. On the first API call of a client instance, the SDK may attach an `x-chargebee-sdk-telemetry` header listing enabled feature codes (`telemetryAdapter`, custom HTTP client, retry config). Later calls on the same client do not send the header again. A default client with no optional features sends no telemetry header.
+* Disable SDK telemetry with `sdkTelemetryEnabled: false`.
+* Exported `SDK_TELEMETRY_HEADER_NAME` from the CJS and ESM entry points.
+
+
 ### v3.31.0 (2026-08-19)
 * * *
 ### New Resources:

package/README.md

@@ -602,6 +602,20 @@ const chargebee = new Chargebee({
 
 These examples demonstrate how to implement and inject custom clients using `axios` and `ky`, respectively.
 
+### SDK telemetry
+
+By default, the library sends anonymous usage telemetry to Chargebee. This helps us improve the SDK and API.
+
+You can disable this behavior if you prefer:
+
+```javascript
+const chargebee = new Chargebee({
+  site: 'your-site',
+  apiKey: 'your-api-key',
+  sdkTelemetryEnabled: false,
+});
+```
+
 ### Telemetry (OpenTelemetry)
 
 Optional. Pass a `telemetryAdapter` when you want Chargebee API calls traced in your observability stack (Datadog, Splunk, Honeycomb, Jaeger, etc.). The SDK ships a ready-to-use OpenTelemetry adapter, so for most setups you only need to add `@opentelemetry/api` and wire the adapter on the client.

package/cjs/RequestWrapper.js

@@ -68,6 +68,15 @@ class RequestWrapper {
         if (this.envArg.telemetryAdapter !== undefined) {
             _env.telemetryAdapter = this.envArg.telemetryAdapter;
         }
+        if (this.envArg.sdkTelemetryState !== undefined) {
+            _env.sdkTelemetryState = this.envArg.sdkTelemetryState;
+        }
+        if (this.envArg.sdkTelemetryEnabled !== undefined) {
+            _env.sdkTelemetryEnabled = this.envArg.sdkTelemetryEnabled;
+        }
+        if (this.envArg.httpClientIsCustom !== undefined) {
+            _env.httpClientIsCustom = this.envArg.httpClientIsCustom;
+        }
         const env = _env;
         const retryConfig = Object.assign({ enabled: false, maxRetries: 3, delayMs: 200, retryOn: [500, 502, 503, 504] }, env.retryConfig);
         const urlIdParam = this.apiCall.hasIdInUrl ? this.args[0] : null;
@@ -142,6 +151,7 @@ class RequestWrapper {
                     : (0, util_js_1.encodeParams)(requestParams, undefined, undefined, undefined, jsonKeys);
             }
             const requestHeaders = Object.assign(Object.assign({}, this.httpHeaders), telemetryHeaders);
+            (0, index_js_1.attachSdkTelemetryHeader)(env, requestHeaders);
             const contentType = this.apiCall.isJsonRequest
                 ? 'application/json;charset=UTF-8'
                 : 'application/x-www-form-urlencoded; charset=utf-8';
@@ -264,9 +274,10 @@ class RequestWrapper {
                 throw err;
             }
         };
-        const promise = telemetryAdapter !== undefined
+        const executeCall = () => telemetryAdapter !== undefined
             ? runWithTelemetry(telemetryAdapter)
             : withRetry(0, requestStartTime);
+        const promise = executeCall();
         return (0, util_js_1.callbackifyPromise)(promise);
     }
     _createHeaders(httpHeaders) {

package/cjs/chargebee.cjs.js

@@ -21,5 +21,6 @@ module.exports.WebhookAuthenticationError = handler_js_1.WebhookAuthenticationEr
 module.exports.WebhookPayloadValidationError = handler_js_1.WebhookPayloadValidationError;
 module.exports.WebhookPayloadParseError = handler_js_1.WebhookPayloadParseError;
 module.exports.TelemetryAttributeKeys = index_js_1.TelemetryAttributeKeys;
+module.exports.SDK_TELEMETRY_HEADER_NAME = index_js_1.SDK_TELEMETRY_HEADER_NAME;
 // Export validation error class
 module.exports.ChargebeeZodValidationError = chargebeeZodValidationError_js_1.ChargebeeZodValidationError;

package/cjs/createChargebee.js

@@ -18,14 +18,18 @@ const api_endpoints_js_1 = require("./resources/api_endpoints.js");
 const util_js_1 = require("./util.js");
 const asyncApiSupport_js_1 = require("./asyncApiSupport.js");
 const handler_js_1 = require("./resources/webhook/handler.js");
+const index_js_1 = require("./telemetry/index.js");
 const CreateChargebee = (httpClient) => {
     const Chargebee = function (conf) {
         this._env = Object.assign({}, environment_js_1.Environment);
-        const { telemetryAdapter, httpClient: configHttpClient } = conf, confToMerge = __rest(conf, ["telemetryAdapter", "httpClient"]);
+        const { telemetryAdapter, httpClient: configHttpClient, sdkTelemetryEnabled } = conf, confToMerge = __rest(conf, ["telemetryAdapter", "httpClient", "sdkTelemetryEnabled"]);
         (0, util_js_1.extend)(true, this._env, confToMerge);
         // @ts-ignore
         this._env.httpClient =
             configHttpClient != null ? configHttpClient : httpClient;
+        this._env.sdkTelemetryState = new index_js_1.SdkTelemetryState();
+        this._env.sdkTelemetryEnabled = sdkTelemetryEnabled !== false;
+        this._env.httpClientIsCustom = configHttpClient != null;
         if (telemetryAdapter !== undefined) {
             this._env.telemetryAdapter = telemetryAdapter;
         }

package/cjs/environment.js

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

package/cjs/schema/estimate.schema.js

@@ -8,7 +8,7 @@ const zod_1 = require("zod");
 //Estimate.createSubscription
 const CreateSubscriptionEstimateSubscriptionSchema = zod_1.z.object({
     id: zod_1.z.string().max(50).optional(),
-    plan_id: zod_1.z.string().max(100),
+    plan_id: zod_1.z.string().max(100).optional(),
     plan_quantity: zod_1.z.number().int().min(1).optional(),
     plan_quantity_in_decimal: zod_1.z.string().max(33).optional(),
     plan_unit_price: zod_1.z.number().int().min(0).optional(),
@@ -359,7 +359,7 @@ exports.CreateSubItemEstimateEstimateBodySchema = CreateSubItemEstimateEstimateB
 //Estimate.createSubForCustomerEstimate
 const CreateSubForCustomerEstimateEstimateSubscriptionSchema = zod_1.z.object({
     id: zod_1.z.string().max(50).optional(),
-    plan_id: zod_1.z.string().max(100),
+    plan_id: zod_1.z.string().max(100).optional(),
     plan_quantity: zod_1.z.number().int().min(1).optional(),
     plan_quantity_in_decimal: zod_1.z.string().max(33).optional(),
     plan_unit_price: zod_1.z.number().int().min(0).optional(),
@@ -1187,7 +1187,7 @@ const GiftSubscriptionEstimateShippingAddressSchema = zod_1.z.object({
         .optional(),
 });
 const GiftSubscriptionEstimateSubscriptionSchema = zod_1.z.object({
-    plan_id: zod_1.z.string().max(100),
+    plan_id: zod_1.z.string().max(100).optional(),
     plan_quantity: zod_1.z.number().int().min(1).optional(),
     plan_quantity_in_decimal: zod_1.z.string().max(33).optional(),
 });

package/cjs/schema/gift.schema.js

@@ -102,7 +102,7 @@ const CreateGiftShippingAddressSchema = zod_1.z.object({
         .optional(),
 });
 const CreateGiftSubscriptionSchema = zod_1.z.looseObject({
-    plan_id: zod_1.z.string().max(100),
+    plan_id: zod_1.z.string().max(100).optional(),
     plan_quantity: zod_1.z.number().int().min(1).optional(),
     plan_quantity_in_decimal: zod_1.z.string().max(33).optional(),
 });

package/cjs/schema/hosted_page.schema.js

@@ -8,7 +8,7 @@ const zod_1 = require("zod");
 //HostedPage.checkoutNew
 const CheckoutNewHostedPageSubscriptionSchema = zod_1.z.looseObject({
     id: zod_1.z.string().max(50).optional(),
-    plan_id: zod_1.z.string().max(100),
+    plan_id: zod_1.z.string().max(100).optional(),
     plan_quantity: zod_1.z.number().int().min(1).optional(),
     plan_quantity_in_decimal: zod_1.z.string().max(33).optional(),
     plan_unit_price: zod_1.z.number().int().min(0).optional(),
@@ -1551,7 +1551,7 @@ const CheckoutGiftHostedPageGifterSchema = zod_1.z.object({
     customer_id: zod_1.z.string().max(50).optional(),
 });
 const CheckoutGiftHostedPageSubscriptionSchema = zod_1.z.looseObject({
-    plan_id: zod_1.z.string().max(100),
+    plan_id: zod_1.z.string().max(100).optional(),
     plan_quantity: zod_1.z.number().int().min(1).optional(),
     plan_quantity_in_decimal: zod_1.z.string().max(33).optional(),
     coupon: zod_1.z.string().max(100).optional(),

package/cjs/schema/omnichannel_subscription.schema.js

@@ -34,16 +34,16 @@ const ListOmnichannelSubscriptionIdAtSourceSchema = zod_1.z.object({
     not_in: zod_1.z.string().regex(RegExp('^\\[(.*)(,.*)*\\]$')).optional(),
 });
 const ListOmnichannelSubscriptionUpdatedAtSchema = zod_1.z.object({
-    after: zod_1.z.string().regex(RegExp('^\\d{10}$')).optional(),
-    on: zod_1.z.string().regex(RegExp('^\\d{10}$')).optional(),
     before: zod_1.z.string().regex(RegExp('^\\d{10}$')).optional(),
     between: zod_1.z.string().regex(RegExp('^\\[\\d{10},\\d{10}\\]$')).optional(),
-});
-const ListOmnichannelSubscriptionPurchasedAtSchema = zod_1.z.object({
     after: zod_1.z.string().regex(RegExp('^\\d{10}$')).optional(),
     on: zod_1.z.string().regex(RegExp('^\\d{10}$')).optional(),
+});
+const ListOmnichannelSubscriptionPurchasedAtSchema = zod_1.z.object({
     before: zod_1.z.string().regex(RegExp('^\\d{10}$')).optional(),
     between: zod_1.z.string().regex(RegExp('^\\[\\d{10},\\d{10}\\]$')).optional(),
+    after: zod_1.z.string().regex(RegExp('^\\d{10}$')).optional(),
+    on: zod_1.z.string().regex(RegExp('^\\d{10}$')).optional(),
 });
 const ListOmnichannelSubscriptionSortBySchema = zod_1.z.looseObject({
     asc: zod_1.z.enum(['created_at', 'updated_at']).optional(),

package/cjs/schema/quote.schema.js

@@ -9,7 +9,7 @@ const zod_1 = require("zod");
 const CreateSubForCustomerQuoteQuoteSubscriptionSchema = zod_1.z.object({
     id: zod_1.z.string().max(50).optional(),
     po_number: zod_1.z.string().max(100).optional(),
-    plan_id: zod_1.z.string().max(100),
+    plan_id: zod_1.z.string().max(100).optional(),
     plan_quantity: zod_1.z.number().int().min(1).optional(),
     plan_quantity_in_decimal: zod_1.z.string().max(33).optional(),
     plan_unit_price: zod_1.z.number().int().min(0).optional(),
@@ -117,7 +117,7 @@ exports.CreateSubForCustomerQuoteQuoteBodySchema = CreateSubForCustomerQuoteQuot
 const EditCreateSubForCustomerQuoteQuoteSubscriptionSchema = zod_1.z.object({
     id: zod_1.z.string().max(50).optional(),
     po_number: zod_1.z.string().max(100).optional(),
-    plan_id: zod_1.z.string().max(100),
+    plan_id: zod_1.z.string().max(100).optional(),
     plan_quantity: zod_1.z.number().int().min(1).optional(),
     plan_quantity_in_decimal: zod_1.z.string().max(33).optional(),
     plan_unit_price: zod_1.z.number().int().min(0).optional(),

package/cjs/schema/subscription.schema.js

@@ -451,7 +451,7 @@ const CreateSubscriptionCouponsSchema = zod_1.z.object({
 });
 const CreateSubscriptionBodySchema = zod_1.z.looseObject({
     id: zod_1.z.string().max(50).optional(),
-    plan_id: zod_1.z.string().max(100),
+    plan_id: zod_1.z.string().max(100).optional(),
     plan_quantity: zod_1.z.number().int().min(1).optional(),
     plan_quantity_in_decimal: zod_1.z.string().max(33).optional(),
     plan_unit_price: zod_1.z.number().int().min(0).optional(),
@@ -657,7 +657,7 @@ const CreateForCustomerSubscriptionCouponsSchema = zod_1.z.object({
 });
 const CreateForCustomerSubscriptionBodySchema = zod_1.z.looseObject({
     id: zod_1.z.string().max(50).optional(),
-    plan_id: zod_1.z.string().max(100),
+    plan_id: zod_1.z.string().max(100).optional(),
     plan_quantity: zod_1.z.number().int().min(1).optional(),
     plan_quantity_in_decimal: zod_1.z.string().max(33).optional(),
     plan_unit_price: zod_1.z.number().int().min(0).optional(),
@@ -2799,7 +2799,7 @@ const ImportSubscriptionSubscriptionCouponsSchema = zod_1.z.object({
 const ImportSubscriptionSubscriptionBodySchema = zod_1.z.looseObject({
     id: zod_1.z.string().max(50).optional(),
     client_profile_id: zod_1.z.string().max(50).optional(),
-    plan_id: zod_1.z.string().max(100),
+    plan_id: zod_1.z.string().max(100).optional(),
     plan_quantity: zod_1.z.number().int().min(1).optional(),
     plan_quantity_in_decimal: zod_1.z.string().max(33).optional(),
     plan_unit_price: zod_1.z.number().int().min(0).optional(),
@@ -2943,7 +2943,7 @@ const ImportForCustomerSubscriptionCouponsSchema = zod_1.z.object({
 });
 const ImportForCustomerSubscriptionBodySchema = zod_1.z.looseObject({
     id: zod_1.z.string().max(50).optional(),
-    plan_id: zod_1.z.string().max(100),
+    plan_id: zod_1.z.string().max(100).optional(),
     plan_quantity: zod_1.z.number().int().min(1).optional(),
     plan_quantity_in_decimal: zod_1.z.string().max(33).optional(),
     plan_unit_price: zod_1.z.number().int().min(0).optional(),

package/cjs/telemetry/index.js

@@ -6,7 +6,7 @@
  * Copyright 2026 Chargebee Inc.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveChargebeeApiVersion = exports.extractRequestTelemetryError = exports.extractHttpStatusCode = exports.buildSpanName = exports.buildRequestTelemetryResult = exports.buildRequestTelemetryContext = exports.buildRequestStartSpanAttributes = exports.buildRequestHeaderSpanAttributes = exports.buildRequestEndSpanAttributes = exports.NoOpTelemetryAdapter = exports.NO_OP_TELEMETRY_ADAPTER = exports.TelemetryAttributeKeys = exports.TELEMETRY_SPAN_NAME_PREFIX = exports.HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX = exports.CHARGEBEE_TELEMETRY_HEADER_PREFIX = exports.CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX = exports.CHARGEBEE_SDK_NAME = void 0;
+exports.attachSdkTelemetryHeader = exports.buildSdkTelemetryHeader = exports.SdkTelemetryState = exports.SdkTelemetryFeature = exports.SDK_TELEMETRY_MAX_HEADER_BYTES = exports.SDK_TELEMETRY_HEADER_NAME = exports.SDK_TELEMETRY_FEATURES_KEY = exports.resolveChargebeeApiVersion = exports.extractRequestTelemetryError = exports.extractHttpStatusCode = exports.buildSpanName = exports.buildRequestTelemetryResult = exports.buildRequestTelemetryContext = exports.buildRequestStartSpanAttributes = exports.buildRequestHeaderSpanAttributes = exports.buildRequestEndSpanAttributes = exports.NoOpTelemetryAdapter = exports.NO_OP_TELEMETRY_ADAPTER = exports.TelemetryAttributeKeys = exports.TELEMETRY_SPAN_NAME_PREFIX = exports.HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX = exports.CHARGEBEE_TELEMETRY_HEADER_PREFIX = exports.CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX = exports.CHARGEBEE_SDK_NAME = void 0;
 var types_js_1 = require("./types.js");
 Object.defineProperty(exports, "CHARGEBEE_SDK_NAME", { enumerable: true, get: function () { return types_js_1.CHARGEBEE_SDK_NAME; } });
 Object.defineProperty(exports, "CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX", { enumerable: true, get: function () { return types_js_1.CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX; } });
@@ -26,3 +26,15 @@ Object.defineProperty(exports, "buildSpanName", { enumerable: true, get: functio
 Object.defineProperty(exports, "extractHttpStatusCode", { enumerable: true, get: function () { return TelemetryAdapter_js_1.extractHttpStatusCode; } });
 Object.defineProperty(exports, "extractRequestTelemetryError", { enumerable: true, get: function () { return TelemetryAdapter_js_1.extractRequestTelemetryError; } });
 Object.defineProperty(exports, "resolveChargebeeApiVersion", { enumerable: true, get: function () { return TelemetryAdapter_js_1.resolveChargebeeApiVersion; } });
+var sdkTelemetryHeader_js_1 = require("./sdkTelemetryHeader.js");
+Object.defineProperty(exports, "SDK_TELEMETRY_FEATURES_KEY", { enumerable: true, get: function () { return sdkTelemetryHeader_js_1.SDK_TELEMETRY_FEATURES_KEY; } });
+Object.defineProperty(exports, "SDK_TELEMETRY_HEADER_NAME", { enumerable: true, get: function () { return sdkTelemetryHeader_js_1.SDK_TELEMETRY_HEADER_NAME; } });
+Object.defineProperty(exports, "SDK_TELEMETRY_MAX_HEADER_BYTES", { enumerable: true, get: function () { return sdkTelemetryHeader_js_1.SDK_TELEMETRY_MAX_HEADER_BYTES; } });
+var sdkTelemetryFeature_js_1 = require("./sdkTelemetryFeature.js");
+Object.defineProperty(exports, "SdkTelemetryFeature", { enumerable: true, get: function () { return sdkTelemetryFeature_js_1.SdkTelemetryFeature; } });
+var sdkTelemetryState_js_1 = require("./sdkTelemetryState.js");
+Object.defineProperty(exports, "SdkTelemetryState", { enumerable: true, get: function () { return sdkTelemetryState_js_1.SdkTelemetryState; } });
+var sdkTelemetryHeaderBuilder_js_1 = require("./sdkTelemetryHeaderBuilder.js");
+Object.defineProperty(exports, "buildSdkTelemetryHeader", { enumerable: true, get: function () { return sdkTelemetryHeaderBuilder_js_1.buildSdkTelemetryHeader; } });
+var sdkTelemetryEmitter_js_1 = require("./sdkTelemetryEmitter.js");
+Object.defineProperty(exports, "attachSdkTelemetryHeader", { enumerable: true, get: function () { return sdkTelemetryEmitter_js_1.attachSdkTelemetryHeader; } });

package/cjs/telemetry/sdkTelemetryEmitter.js

@@ -0,0 +1,64 @@
+"use strict";
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachSdkTelemetryHeader = attachSdkTelemetryHeader;
+const sdkTelemetryHeaderBuilder_js_1 = require("./sdkTelemetryHeaderBuilder.js");
+const sdkTelemetryFeature_js_1 = require("./sdkTelemetryFeature.js");
+const sdkTelemetryHeader_js_1 = require("./sdkTelemetryHeader.js");
+/**
+ * Emits the anonymous SDK telemetry request header, independently of any customer telemetry
+ * adapter.
+ *
+ * On the first API call of a client instance, attaches {@code f;…} with enabled feature codes when
+ * any are present; omits the header when none are enabled. Later calls on the same client never
+ * attach again. SDK identity is correlated via User-Agent. Every failure path is swallowed and
+ * logged at WARNING: telemetry must never fail an API call.
+ */
+function attachSdkTelemetryHeader(env, headers) {
+    var _a;
+    if (env.sdkTelemetryEnabled === false) {
+        return;
+    }
+    try {
+        if (!((_a = env.sdkTelemetryState) === null || _a === void 0 ? void 0 : _a.tryMarkEmitted())) {
+            return;
+        }
+        const headerValue = (0, sdkTelemetryHeaderBuilder_js_1.buildSdkTelemetryHeader)(resolveFeatures(env));
+        if (!headerValue) {
+            return;
+        }
+        headers[sdkTelemetryHeader_js_1.SDK_TELEMETRY_HEADER_NAME] = headerValue;
+    }
+    catch (err) {
+        logSuppressed('attach header', err);
+    }
+}
+/** Collects enabled feature codes for the current client configuration. */
+function resolveFeatures(env) {
+    const features = [];
+    if (env.telemetryAdapter !== undefined) {
+        features.push(sdkTelemetryFeature_js_1.SdkTelemetryFeature.TELEMETRY_ADAPTER);
+    }
+    if (env.httpClientIsCustom) {
+        features.push(sdkTelemetryFeature_js_1.SdkTelemetryFeature.CUSTOM_TRANSPORT);
+    }
+    if (isRetryConfigActive(env)) {
+        features.push(sdkTelemetryFeature_js_1.SdkTelemetryFeature.RETRY_CONFIG);
+    }
+    return features;
+}
+/** Whether retries are enabled on the client. */
+function isRetryConfigActive(env) {
+    var _a;
+    return ((_a = env.retryConfig) === null || _a === void 0 ? void 0 : _a.enabled) === true;
+}
+/** Logs a suppressed telemetry failure without affecting the API call. */
+function logSuppressed(step, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`SDK telemetry could not ${step} (${message}); API call unaffected.`, err);
+}

package/cjs/telemetry/sdkTelemetryFeature.js

@@ -0,0 +1,22 @@
+"use strict";
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SdkTelemetryFeature = void 0;
+/**
+ * SDK configuration features reported under the {@code f} segment of
+ * {@link SDK_TELEMETRY_HEADER_NAME}. Wire codes are maintained in sdk-generator.
+ */
+var SdkTelemetryFeature;
+(function (SdkTelemetryFeature) {
+    /** Customer TelemetryAdapter configured. */
+    SdkTelemetryFeature["TELEMETRY_ADAPTER"] = "ta";
+    /** Custom HTTP client configured. */
+    SdkTelemetryFeature["CUSTOM_TRANSPORT"] = "ct";
+    /** Retries enabled on the client. */
+    SdkTelemetryFeature["RETRY_CONFIG"] = "rc";
+})(SdkTelemetryFeature || (exports.SdkTelemetryFeature = SdkTelemetryFeature = {}));

package/cjs/telemetry/sdkTelemetryHeader.js

@@ -0,0 +1,15 @@
+"use strict";
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_TELEMETRY_FEATURES_KEY = exports.SDK_TELEMETRY_MAX_HEADER_BYTES = exports.SDK_TELEMETRY_HEADER_NAME = void 0;
+/** Constants for the anonymous SDK telemetry request header. */
+exports.SDK_TELEMETRY_HEADER_NAME = 'x-chargebee-sdk-telemetry';
+/** Defensive size cap; feature-only values are tiny. */
+exports.SDK_TELEMETRY_MAX_HEADER_BYTES = 4096;
+/** RFC 9651 sf-list item name for the features segment. */
+exports.SDK_TELEMETRY_FEATURES_KEY = 'f';

package/cjs/telemetry/sdkTelemetryHeaderBuilder.js

@@ -0,0 +1,34 @@
+"use strict";
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSdkTelemetryHeader = buildSdkTelemetryHeader;
+const sdkTelemetryHeader_js_1 = require("./sdkTelemetryHeader.js");
+/**
+ * Builds RFC 9651 values for {@link SDK_TELEMETRY_HEADER_NAME}: a features segment keyed by
+ * {@link SDK_TELEMETRY_FEATURES_KEY} with enabled feature codes as boolean params
+ * (for example {@code f;ta;rc}). Correlate SDK identity via User-Agent.
+ */
+function buildSdkTelemetryHeader(features) {
+    if (!features || features.length === 0) {
+        return undefined;
+    }
+    let value = sdkTelemetryHeader_js_1.SDK_TELEMETRY_FEATURES_KEY;
+    for (const feature of features) {
+        if (feature == null) {
+            continue;
+        }
+        value += `;${feature}`;
+    }
+    if (value.length === sdkTelemetryHeader_js_1.SDK_TELEMETRY_FEATURES_KEY.length) {
+        return undefined;
+    }
+    if (new TextEncoder().encode(value).length > sdkTelemetryHeader_js_1.SDK_TELEMETRY_MAX_HEADER_BYTES) {
+        return undefined;
+    }
+    return value;
+}

package/cjs/telemetry/sdkTelemetryState.js

@@ -0,0 +1,36 @@
+"use strict";
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SdkTelemetryState = void 0;
+/**
+ * Per-client gate so the SDK telemetry header is considered at most once per client instance.
+ */
+class SdkTelemetryState {
+    constructor() {
+        this.emitted = false;
+    }
+    /**
+     * Claims the single emission slot for this client. Returns true only for the first caller.
+     */
+    tryMarkEmitted() {
+        if (this.emitted) {
+            return false;
+        }
+        this.emitted = true;
+        return true;
+    }
+    /** Whether this client has already considered emitting the telemetry header. */
+    hasEmitted() {
+        return this.emitted;
+    }
+    /** Clears the emission gate (tests only). */
+    clear() {
+        this.emitted = false;
+    }
+}
+exports.SdkTelemetryState = SdkTelemetryState;

package/esm/RequestWrapper.js

@@ -1,5 +1,5 @@
 import { extend, callbackifyPromise, getApiURL, encodeListParams, encodeParams, serialize, getHost, log, generateUUIDv4 as uuidv4, } from './util.js';
-import { buildRequestTelemetryContext, buildRequestTelemetryResult, extractHttpStatusCode, extractRequestTelemetryError, resolveChargebeeApiVersion, } from './telemetry/index.js';
+import { buildRequestTelemetryContext, buildRequestTelemetryResult, extractHttpStatusCode, extractRequestTelemetryError, resolveChargebeeApiVersion, attachSdkTelemetryHeader, } from './telemetry/index.js';
 import { handleResponse } from './coreCommon.js';
 import { Buffer } from 'node:buffer';
 import { ChargebeeZodValidationError } from './chargebeeZodValidationError.js';
@@ -65,6 +65,15 @@ export class RequestWrapper {
         if (this.envArg.telemetryAdapter !== undefined) {
             _env.telemetryAdapter = this.envArg.telemetryAdapter;
         }
+        if (this.envArg.sdkTelemetryState !== undefined) {
+            _env.sdkTelemetryState = this.envArg.sdkTelemetryState;
+        }
+        if (this.envArg.sdkTelemetryEnabled !== undefined) {
+            _env.sdkTelemetryEnabled = this.envArg.sdkTelemetryEnabled;
+        }
+        if (this.envArg.httpClientIsCustom !== undefined) {
+            _env.httpClientIsCustom = this.envArg.httpClientIsCustom;
+        }
         const env = _env;
         const retryConfig = Object.assign({ enabled: false, maxRetries: 3, delayMs: 200, retryOn: [500, 502, 503, 504] }, env.retryConfig);
         const urlIdParam = this.apiCall.hasIdInUrl ? this.args[0] : null;
@@ -139,6 +148,7 @@ export class RequestWrapper {
                     : encodeParams(requestParams, undefined, undefined, undefined, jsonKeys);
             }
             const requestHeaders = Object.assign(Object.assign({}, this.httpHeaders), telemetryHeaders);
+            attachSdkTelemetryHeader(env, requestHeaders);
             const contentType = this.apiCall.isJsonRequest
                 ? 'application/json;charset=UTF-8'
                 : 'application/x-www-form-urlencoded; charset=utf-8';
@@ -261,9 +271,10 @@ export class RequestWrapper {
                 throw err;
             }
         };
-        const promise = telemetryAdapter !== undefined
+        const executeCall = () => telemetryAdapter !== undefined
             ? runWithTelemetry(telemetryAdapter)
             : withRetry(0, requestStartTime);
+        const promise = executeCall();
         return callbackifyPromise(promise);
     }
     _createHeaders(httpHeaders) {

package/esm/chargebee.esm.js

@@ -7,6 +7,6 @@ export default Chargebee;
 export { WebhookEventType, WebhookContentType, } from './resources/webhook/handler.js';
 export { basicAuthValidator } from './resources/webhook/auth.js';
 export { WebhookError, WebhookAuthenticationError, WebhookPayloadValidationError, WebhookPayloadParseError, } from './resources/webhook/handler.js';
-export { TelemetryAttributeKeys } from './telemetry/index.js';
+export { TelemetryAttributeKeys, SDK_TELEMETRY_HEADER_NAME, } from './telemetry/index.js';
 // Export validation error class
 export { ChargebeeZodValidationError } from './chargebeeZodValidationError.js';

package/esm/createChargebee.js

@@ -15,14 +15,18 @@ import { Endpoints } from './resources/api_endpoints.js';
 import { extend, sleep } from './util.js';
 import { waitForProcessToComplete } from './asyncApiSupport.js';
 import { WebhookHandler, createDefaultHandler, } from './resources/webhook/handler.js';
+import { SdkTelemetryState } from './telemetry/index.js';
 export const CreateChargebee = (httpClient) => {
     const Chargebee = function (conf) {
         this._env = Object.assign({}, Environment);
-        const { telemetryAdapter, httpClient: configHttpClient } = conf, confToMerge = __rest(conf, ["telemetryAdapter", "httpClient"]);
+        const { telemetryAdapter, httpClient: configHttpClient, sdkTelemetryEnabled } = conf, confToMerge = __rest(conf, ["telemetryAdapter", "httpClient", "sdkTelemetryEnabled"]);
         extend(true, this._env, confToMerge);
         // @ts-ignore
         this._env.httpClient =
             configHttpClient != null ? configHttpClient : httpClient;
+        this._env.sdkTelemetryState = new SdkTelemetryState();
+        this._env.sdkTelemetryEnabled = sdkTelemetryEnabled !== false;
+        this._env.httpClientIsCustom = configHttpClient != null;
         if (telemetryAdapter !== undefined) {
             this._env.telemetryAdapter = telemetryAdapter;
         }

package/esm/environment.js

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

package/esm/schema/estimate.schema.js

@@ -5,7 +5,7 @@ import { z } from 'zod';
 //Estimate.createSubscription
 const CreateSubscriptionEstimateSubscriptionSchema = z.object({
     id: z.string().max(50).optional(),
-    plan_id: z.string().max(100),
+    plan_id: z.string().max(100).optional(),
     plan_quantity: z.number().int().min(1).optional(),
     plan_quantity_in_decimal: z.string().max(33).optional(),
     plan_unit_price: z.number().int().min(0).optional(),
@@ -356,7 +356,7 @@ export { CreateSubItemEstimateEstimateBodySchema };
 //Estimate.createSubForCustomerEstimate
 const CreateSubForCustomerEstimateEstimateSubscriptionSchema = z.object({
     id: z.string().max(50).optional(),
-    plan_id: z.string().max(100),
+    plan_id: z.string().max(100).optional(),
     plan_quantity: z.number().int().min(1).optional(),
     plan_quantity_in_decimal: z.string().max(33).optional(),
     plan_unit_price: z.number().int().min(0).optional(),
@@ -1184,7 +1184,7 @@ const GiftSubscriptionEstimateShippingAddressSchema = z.object({
         .optional(),
 });
 const GiftSubscriptionEstimateSubscriptionSchema = z.object({
-    plan_id: z.string().max(100),
+    plan_id: z.string().max(100).optional(),
     plan_quantity: z.number().int().min(1).optional(),
     plan_quantity_in_decimal: z.string().max(33).optional(),
 });

package/esm/schema/gift.schema.js

@@ -99,7 +99,7 @@ const CreateGiftShippingAddressSchema = z.object({
         .optional(),
 });
 const CreateGiftSubscriptionSchema = z.looseObject({
-    plan_id: z.string().max(100),
+    plan_id: z.string().max(100).optional(),
     plan_quantity: z.number().int().min(1).optional(),
     plan_quantity_in_decimal: z.string().max(33).optional(),
 });

package/esm/schema/hosted_page.schema.js

@@ -5,7 +5,7 @@ import { z } from 'zod';
 //HostedPage.checkoutNew
 const CheckoutNewHostedPageSubscriptionSchema = z.looseObject({
     id: z.string().max(50).optional(),
-    plan_id: z.string().max(100),
+    plan_id: z.string().max(100).optional(),
     plan_quantity: z.number().int().min(1).optional(),
     plan_quantity_in_decimal: z.string().max(33).optional(),
     plan_unit_price: z.number().int().min(0).optional(),
@@ -1548,7 +1548,7 @@ const CheckoutGiftHostedPageGifterSchema = z.object({
     customer_id: z.string().max(50).optional(),
 });
 const CheckoutGiftHostedPageSubscriptionSchema = z.looseObject({
-    plan_id: z.string().max(100),
+    plan_id: z.string().max(100).optional(),
     plan_quantity: z.number().int().min(1).optional(),
     plan_quantity_in_decimal: z.string().max(33).optional(),
     coupon: z.string().max(100).optional(),

package/esm/schema/omnichannel_subscription.schema.js

@@ -31,16 +31,16 @@ const ListOmnichannelSubscriptionIdAtSourceSchema = z.object({
     not_in: z.string().regex(RegExp('^\\[(.*)(,.*)*\\]$')).optional(),
 });
 const ListOmnichannelSubscriptionUpdatedAtSchema = z.object({
-    after: z.string().regex(RegExp('^\\d{10}$')).optional(),
-    on: z.string().regex(RegExp('^\\d{10}$')).optional(),
     before: z.string().regex(RegExp('^\\d{10}$')).optional(),
     between: z.string().regex(RegExp('^\\[\\d{10},\\d{10}\\]$')).optional(),
-});
-const ListOmnichannelSubscriptionPurchasedAtSchema = z.object({
     after: z.string().regex(RegExp('^\\d{10}$')).optional(),
     on: z.string().regex(RegExp('^\\d{10}$')).optional(),
+});
+const ListOmnichannelSubscriptionPurchasedAtSchema = z.object({
     before: z.string().regex(RegExp('^\\d{10}$')).optional(),
     between: z.string().regex(RegExp('^\\[\\d{10},\\d{10}\\]$')).optional(),
+    after: z.string().regex(RegExp('^\\d{10}$')).optional(),
+    on: z.string().regex(RegExp('^\\d{10}$')).optional(),
 });
 const ListOmnichannelSubscriptionSortBySchema = z.looseObject({
     asc: z.enum(['created_at', 'updated_at']).optional(),
@@ -115,7 +115,7 @@ const OmnichannelTransactionsforomnichannelsubscriptionOmnichannelSubscriptionBo
     limit: z.number().int().min(1).max(100).optional(),
     offset: z.string().max(1000).optional(),
 });
-export { OmnichannelTransactionsforomnichannelsubscriptionOmnichannelSubscriptionBodySchema };
+export { OmnichannelTransactionsforomnichannelsubscriptionOmnichannelSubscriptionBodySchema, };
 //OmnichannelSubscription.move
 const MoveOmnichannelSubscriptionBodySchema = z.looseObject({
     to_customer_id: z.string().max(50),

package/esm/schema/quote.schema.js

@@ -6,7 +6,7 @@ import { z } from 'zod';
 const CreateSubForCustomerQuoteQuoteSubscriptionSchema = z.object({
     id: z.string().max(50).optional(),
     po_number: z.string().max(100).optional(),
-    plan_id: z.string().max(100),
+    plan_id: z.string().max(100).optional(),
     plan_quantity: z.number().int().min(1).optional(),
     plan_quantity_in_decimal: z.string().max(33).optional(),
     plan_unit_price: z.number().int().min(0).optional(),
@@ -114,7 +114,7 @@ export { CreateSubForCustomerQuoteQuoteBodySchema };
 const EditCreateSubForCustomerQuoteQuoteSubscriptionSchema = z.object({
     id: z.string().max(50).optional(),
     po_number: z.string().max(100).optional(),
-    plan_id: z.string().max(100),
+    plan_id: z.string().max(100).optional(),
     plan_quantity: z.number().int().min(1).optional(),
     plan_quantity_in_decimal: z.string().max(33).optional(),
     plan_unit_price: z.number().int().min(0).optional(),

package/esm/schema/subscription.schema.js

@@ -448,7 +448,7 @@ const CreateSubscriptionCouponsSchema = z.object({
 });
 const CreateSubscriptionBodySchema = z.looseObject({
     id: z.string().max(50).optional(),
-    plan_id: z.string().max(100),
+    plan_id: z.string().max(100).optional(),
     plan_quantity: z.number().int().min(1).optional(),
     plan_quantity_in_decimal: z.string().max(33).optional(),
     plan_unit_price: z.number().int().min(0).optional(),
@@ -654,7 +654,7 @@ const CreateForCustomerSubscriptionCouponsSchema = z.object({
 });
 const CreateForCustomerSubscriptionBodySchema = z.looseObject({
     id: z.string().max(50).optional(),
-    plan_id: z.string().max(100),
+    plan_id: z.string().max(100).optional(),
     plan_quantity: z.number().int().min(1).optional(),
     plan_quantity_in_decimal: z.string().max(33).optional(),
     plan_unit_price: z.number().int().min(0).optional(),
@@ -2796,7 +2796,7 @@ const ImportSubscriptionSubscriptionCouponsSchema = z.object({
 const ImportSubscriptionSubscriptionBodySchema = z.looseObject({
     id: z.string().max(50).optional(),
     client_profile_id: z.string().max(50).optional(),
-    plan_id: z.string().max(100),
+    plan_id: z.string().max(100).optional(),
     plan_quantity: z.number().int().min(1).optional(),
     plan_quantity_in_decimal: z.string().max(33).optional(),
     plan_unit_price: z.number().int().min(0).optional(),
@@ -2940,7 +2940,7 @@ const ImportForCustomerSubscriptionCouponsSchema = z.object({
 });
 const ImportForCustomerSubscriptionBodySchema = z.looseObject({
     id: z.string().max(50).optional(),
-    plan_id: z.string().max(100),
+    plan_id: z.string().max(100).optional(),
     plan_quantity: z.number().int().min(1).optional(),
     plan_quantity_in_decimal: z.string().max(33).optional(),
     plan_unit_price: z.number().int().min(0).optional(),

package/esm/schema/subscription_entitlement.schema.js

@@ -10,7 +10,7 @@ const SubscriptionEntitlementsForSubscriptionSubscriptionEntitlementBodySchema =
     embed: z.string().max(1000).optional(),
     include_scheduled_overrides: z.boolean().default(false).optional(),
 });
-export { SubscriptionEntitlementsForSubscriptionSubscriptionEntitlementBodySchema };
+export { SubscriptionEntitlementsForSubscriptionSubscriptionEntitlementBodySchema, };
 //SubscriptionEntitlement.setSubscriptionEntitlementAvailability
 const SetSubscriptionEntitlementAvailabilitySubscriptionEntitlementSubscriptionEntitlementsSchema = z.object({
     feature_id: z.array(z.string().max(50).optional()),
@@ -19,4 +19,4 @@ const SetSubscriptionEntitlementAvailabilitySubscriptionEntitlementBodySchema =
     is_enabled: z.boolean(),
     subscription_entitlements: SetSubscriptionEntitlementAvailabilitySubscriptionEntitlementSubscriptionEntitlementsSchema.optional(),
 });
-export { SetSubscriptionEntitlementAvailabilitySubscriptionEntitlementBodySchema };
+export { SetSubscriptionEntitlementAvailabilitySubscriptionEntitlementBodySchema, };

package/esm/telemetry/index.js

@@ -6,3 +6,8 @@
  */
 export { CHARGEBEE_SDK_NAME, CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX, CHARGEBEE_TELEMETRY_HEADER_PREFIX, HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX, TELEMETRY_SPAN_NAME_PREFIX, TelemetryAttributeKeys, } from './types.js';
 export { NO_OP_TELEMETRY_ADAPTER, NoOpTelemetryAdapter, buildRequestEndSpanAttributes, buildRequestHeaderSpanAttributes, buildRequestStartSpanAttributes, buildRequestTelemetryContext, buildRequestTelemetryResult, buildSpanName, extractHttpStatusCode, extractRequestTelemetryError, resolveChargebeeApiVersion, } from './TelemetryAdapter.js';
+export { SDK_TELEMETRY_FEATURES_KEY, SDK_TELEMETRY_HEADER_NAME, SDK_TELEMETRY_MAX_HEADER_BYTES, } from './sdkTelemetryHeader.js';
+export { SdkTelemetryFeature } from './sdkTelemetryFeature.js';
+export { SdkTelemetryState } from './sdkTelemetryState.js';
+export { buildSdkTelemetryHeader } from './sdkTelemetryHeaderBuilder.js';
+export { attachSdkTelemetryHeader, } from './sdkTelemetryEmitter.js';

package/esm/telemetry/sdkTelemetryEmitter.js

@@ -0,0 +1,61 @@
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+import { buildSdkTelemetryHeader } from './sdkTelemetryHeaderBuilder.js';
+import { SdkTelemetryFeature } from './sdkTelemetryFeature.js';
+import { SDK_TELEMETRY_HEADER_NAME } from './sdkTelemetryHeader.js';
+/**
+ * Emits the anonymous SDK telemetry request header, independently of any customer telemetry
+ * adapter.
+ *
+ * On the first API call of a client instance, attaches {@code f;…} with enabled feature codes when
+ * any are present; omits the header when none are enabled. Later calls on the same client never
+ * attach again. SDK identity is correlated via User-Agent. Every failure path is swallowed and
+ * logged at WARNING: telemetry must never fail an API call.
+ */
+export function attachSdkTelemetryHeader(env, headers) {
+    var _a;
+    if (env.sdkTelemetryEnabled === false) {
+        return;
+    }
+    try {
+        if (!((_a = env.sdkTelemetryState) === null || _a === void 0 ? void 0 : _a.tryMarkEmitted())) {
+            return;
+        }
+        const headerValue = buildSdkTelemetryHeader(resolveFeatures(env));
+        if (!headerValue) {
+            return;
+        }
+        headers[SDK_TELEMETRY_HEADER_NAME] = headerValue;
+    }
+    catch (err) {
+        logSuppressed('attach header', err);
+    }
+}
+/** Collects enabled feature codes for the current client configuration. */
+function resolveFeatures(env) {
+    const features = [];
+    if (env.telemetryAdapter !== undefined) {
+        features.push(SdkTelemetryFeature.TELEMETRY_ADAPTER);
+    }
+    if (env.httpClientIsCustom) {
+        features.push(SdkTelemetryFeature.CUSTOM_TRANSPORT);
+    }
+    if (isRetryConfigActive(env)) {
+        features.push(SdkTelemetryFeature.RETRY_CONFIG);
+    }
+    return features;
+}
+/** Whether retries are enabled on the client. */
+function isRetryConfigActive(env) {
+    var _a;
+    return ((_a = env.retryConfig) === null || _a === void 0 ? void 0 : _a.enabled) === true;
+}
+/** Logs a suppressed telemetry failure without affecting the API call. */
+function logSuppressed(step, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`SDK telemetry could not ${step} (${message}); API call unaffected.`, err);
+}

package/esm/telemetry/sdkTelemetryFeature.js

@@ -0,0 +1,19 @@
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+/**
+ * SDK configuration features reported under the {@code f} segment of
+ * {@link SDK_TELEMETRY_HEADER_NAME}. Wire codes are maintained in sdk-generator.
+ */
+export var SdkTelemetryFeature;
+(function (SdkTelemetryFeature) {
+    /** Customer TelemetryAdapter configured. */
+    SdkTelemetryFeature["TELEMETRY_ADAPTER"] = "ta";
+    /** Custom HTTP client configured. */
+    SdkTelemetryFeature["CUSTOM_TRANSPORT"] = "ct";
+    /** Retries enabled on the client. */
+    SdkTelemetryFeature["RETRY_CONFIG"] = "rc";
+})(SdkTelemetryFeature || (SdkTelemetryFeature = {}));

package/esm/telemetry/sdkTelemetryHeader.js

@@ -0,0 +1,12 @@
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+/** Constants for the anonymous SDK telemetry request header. */
+export const SDK_TELEMETRY_HEADER_NAME = 'x-chargebee-sdk-telemetry';
+/** Defensive size cap; feature-only values are tiny. */
+export const SDK_TELEMETRY_MAX_HEADER_BYTES = 4096;
+/** RFC 9651 sf-list item name for the features segment. */
+export const SDK_TELEMETRY_FEATURES_KEY = 'f';

package/esm/telemetry/sdkTelemetryHeaderBuilder.js

@@ -0,0 +1,31 @@
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+import { SDK_TELEMETRY_FEATURES_KEY, SDK_TELEMETRY_MAX_HEADER_BYTES, } from './sdkTelemetryHeader.js';
+/**
+ * Builds RFC 9651 values for {@link SDK_TELEMETRY_HEADER_NAME}: a features segment keyed by
+ * {@link SDK_TELEMETRY_FEATURES_KEY} with enabled feature codes as boolean params
+ * (for example {@code f;ta;rc}). Correlate SDK identity via User-Agent.
+ */
+export function buildSdkTelemetryHeader(features) {
+    if (!features || features.length === 0) {
+        return undefined;
+    }
+    let value = SDK_TELEMETRY_FEATURES_KEY;
+    for (const feature of features) {
+        if (feature == null) {
+            continue;
+        }
+        value += `;${feature}`;
+    }
+    if (value.length === SDK_TELEMETRY_FEATURES_KEY.length) {
+        return undefined;
+    }
+    if (new TextEncoder().encode(value).length > SDK_TELEMETRY_MAX_HEADER_BYTES) {
+        return undefined;
+    }
+    return value;
+}

package/esm/telemetry/sdkTelemetryState.js

@@ -0,0 +1,32 @@
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+/**
+ * Per-client gate so the SDK telemetry header is considered at most once per client instance.
+ */
+export class SdkTelemetryState {
+    constructor() {
+        this.emitted = false;
+    }
+    /**
+     * Claims the single emission slot for this client. Returns true only for the first caller.
+     */
+    tryMarkEmitted() {
+        if (this.emitted) {
+            return false;
+        }
+        this.emitted = true;
+        return true;
+    }
+    /** Whether this client has already considered emitting the telemetry header. */
+    hasEmitted() {
+        return this.emitted;
+    }
+    /** Clears the emission gate (tests only). */
+    clear() {
+        this.emitted = false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chargebee",
-  "version": "3.31.0",
+  "version": "3.33.0",
   "description": "A library for integrating with Chargebee.",
   "scripts": {
     "prepack": "npm ci && npm run build",
@@ -8,7 +8,8 @@
     "build": "npm run build-esm && npm run build-cjs",
     "build-esm": "rm -rf esm && mkdir -p esm && tsc -p tsconfig.esm.json && echo '{\"type\":\"module\"}' > esm/package.json",
     "build-cjs": "rm -rf cjs && mkdir -p cjs && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > cjs/package.json",
-    "prettier": "prettier --write \"src/**/*.ts\" \"types/**/*.d.ts\""
+    "format": "biome format --write",
+    "format:check": "biome format"
   },
   "types": "./types/index.d.ts",
   "keywords": [
@@ -76,22 +77,17 @@
     }
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.7",
     "@opentelemetry/api": "^1.9.0",
     "@types/chai": "^4.3.5",
     "@types/mocha": "^10.0.10",
     "@types/node": "20.12.0",
     "chai": "^4.3.7",
     "mocha": "^10.2.0",
-    "prettier": "^3.3.3",
     "ts-node": "^10.9.1",
     "typescript": "^5.5.4",
     "undici-types": "^7.16.0"
   },
-  "prettier": {
-    "semi": true,
-    "singleQuote": true,
-    "parser": "typescript"
-  },
   "dependencies": {
     "zod": "^4.3.6"
   }

package/types/index.d.ts

@@ -189,14 +189,17 @@ declare module 'chargebee' {
      * @telemetryAdapter optional telemetry adapter for observability (e.g. OpenTelemetry)
      */
     telemetryAdapter?: TelemetryAdapter;
+
+    /**
+     * @sdkTelemetryEnabled when false, the SDK does not send the anonymous x-chargebee-sdk-telemetry header. Default true.
+     */
+    sdkTelemetryEnabled?: boolean;
   };
 
   export interface HttpClientInterface {
     makeApiRequest: (request: Request, timeout: number) => Promise<Response>;
   }
 
-  export type RequestTelemetryHandle = unknown;
-
   export const TelemetryAttributeKeys: {
     readonly URL_FULL: 'url.full';
     readonly HTTP_REQUEST_METHOD: 'http.request.method';
@@ -214,6 +217,10 @@ declare module 'chargebee' {
     readonly CHARGEBEE_ERROR_PARAM: 'chargebee.error.param';
   };
 
+  export const SDK_TELEMETRY_HEADER_NAME: 'x-chargebee-sdk-telemetry';
+
+  export type RequestTelemetryHandle = unknown;
+
   export type RequestTelemetryContext = {
     spanName: string;
     resource: string;

package/types/resources/Coupon.d.ts

@@ -24,8 +24,8 @@ declare module 'chargebee' {
       | 'plans_with_quantity'
       | 'not_applicable';
     apply_on: 'invoice_amount' | 'each_specified_item';
-    plan_constraint: 'none' | 'all' | 'specific' | 'not_applicable';
-    addon_constraint: 'none' | 'all' | 'specific' | 'not_applicable';
+    plan_constraint?: 'none' | 'all' | 'specific' | 'not_applicable';
+    addon_constraint?: 'none' | 'all' | 'specific' | 'not_applicable';
     created_at: number;
     archived_at?: number;
     resource_version?: number;

package/types/resources/Estimate.d.ts

@@ -506,7 +506,7 @@ declare module 'chargebee' {
     }
     export interface SubscriptionCreateSubscriptionInputParam {
       id?: string;
-      plan_id: string;
+      plan_id?: string;
       plan_quantity?: number;
       plan_quantity_in_decimal?: string;
       plan_unit_price?: number;
@@ -667,7 +667,7 @@ declare module 'chargebee' {
     }
     export interface SubscriptionCreateSubForCustomerEstimateInputParam {
       id?: string;
-      plan_id: string;
+      plan_id?: string;
       plan_quantity?: number;
       plan_quantity_in_decimal?: string;
       plan_unit_price?: number;
@@ -1087,7 +1087,7 @@ declare module 'chargebee' {
       additional_information?: any;
     }
     export interface SubscriptionGiftSubscriptionInputParam {
-      plan_id: string;
+      plan_id?: string;
       plan_quantity?: number;
       plan_quantity_in_decimal?: string;
     }

package/types/resources/Gift.d.ts

@@ -244,7 +244,7 @@ declare module 'chargebee' {
       additional_information?: any;
     }
     export interface SubscriptionCreateInputParam {
-      plan_id: string;
+      plan_id?: string;
       plan_quantity?: number;
       plan_quantity_in_decimal?: string;
     }

package/types/resources/HostedPage.d.ts

@@ -25,7 +25,7 @@ declare module 'chargebee' {
       | 'acknowledged';
     failure_reason?: 'card_error' | 'server_error';
     pass_thru_content?: string;
-    embed: boolean;
+    embed?: boolean;
     created_at?: number;
     expires_at?: number;
     layout?: LayoutEnum;
@@ -532,7 +532,7 @@ declare module 'chargebee' {
     }
     export interface SubscriptionCheckoutNewInputParam {
       id?: string;
-      plan_id: string;
+      plan_id?: string;
       plan_quantity?: number;
       plan_quantity_in_decimal?: string;
       plan_unit_price?: number;
@@ -1097,7 +1097,7 @@ declare module 'chargebee' {
       customer_id?: string;
     }
     export interface SubscriptionCheckoutGiftInputParam {
-      plan_id: string;
+      plan_id?: string;
       plan_quantity?: number;
       plan_quantity_in_decimal?: string;
       /**

package/types/resources/Quote.d.ts

@@ -843,7 +843,7 @@ declare module 'chargebee' {
     export interface SubscriptionCreateSubForCustomerQuoteInputParam {
       id?: string;
       po_number?: string;
-      plan_id: string;
+      plan_id?: string;
       plan_quantity?: number;
       plan_quantity_in_decimal?: string;
       plan_unit_price?: number;
@@ -898,7 +898,7 @@ declare module 'chargebee' {
     export interface SubscriptionEditCreateSubForCustomerQuoteInputParam {
       id?: string;
       po_number?: string;
-      plan_id: string;
+      plan_id?: string;
       plan_quantity?: number;
       plan_quantity_in_decimal?: string;
       plan_unit_price?: number;

package/types/resources/QuotedSubscription.d.ts

@@ -4,8 +4,8 @@
 declare module 'chargebee' {
   export interface QuotedSubscription {
     id: string;
-    plan_id: string;
-    plan_quantity: number;
+    plan_id?: string;
+    plan_quantity?: number;
     plan_unit_price?: number;
     setup_fee?: number;
     billing_period?: number;

package/types/resources/Subscription.d.ts

@@ -6,8 +6,8 @@ declare module 'chargebee' {
     [key: string]: unknown;
     id: string;
     currency_code: string;
-    plan_id: string;
-    plan_quantity: number;
+    plan_id?: string;
+    plan_quantity?: number;
     plan_unit_price?: number;
     setup_fee?: number;
     billing_period?: number;
@@ -715,7 +715,7 @@ declare module 'chargebee' {
 
     export interface CreateInputParam {
       id?: string;
-      plan_id: string;
+      plan_id?: string;
       plan_quantity?: number;
       plan_quantity_in_decimal?: string;
       plan_unit_price?: number;
@@ -769,7 +769,7 @@ declare module 'chargebee' {
     }
     export interface CreateForCustomerInputParam {
       id?: string;
-      plan_id: string;
+      plan_id?: string;
       plan_quantity?: number;
       plan_quantity_in_decimal?: string;
       plan_unit_price?: number;
@@ -1087,7 +1087,7 @@ declare module 'chargebee' {
     export interface ImportSubscriptionInputParam {
       id?: string;
       client_profile_id?: string;
-      plan_id: string;
+      plan_id?: string;
       plan_quantity?: number;
       plan_quantity_in_decimal?: string;
       plan_unit_price?: number;
@@ -1135,7 +1135,7 @@ declare module 'chargebee' {
     }
     export interface ImportForCustomerInputParam {
       id?: string;
-      plan_id: string;
+      plan_id?: string;
       plan_quantity?: number;
       plan_quantity_in_decimal?: string;
       plan_unit_price?: number;