{
  "compilerOptions": {
    "target": "ES2020",
    "module": "Node16",
    "moduleResolution": "Node16",
    "esModuleInterop": true,
    "strict": true
  }
}

3. Set environment variables for your Chargebee credentials:

CHARGEBEE_SITE=your-site-name
CHARGEBEE_API_KEY=your-api-key
# Optional webhook Basic Auth:
CHARGEBEE_WEBHOOK_USERNAME=whuser
CHARGEBEE_WEBHOOK_PASSWORD=whpass

4. Import from the package entry point (or directly from the copied source):

import Chargebee from 'chargebee';
// or from source:
import Chargebee from './chargebee/chargebee.esm.js';

5. Instantiate with your credentials before making any API calls:

const chargebee = new Chargebee({
  site: process.env.CHARGEBEE_SITE!,
  apiKey: process.env.CHARGEBEE_API_KEY!,
});

Public API

Chargebee (constructor)

import Chargebee from 'chargebee';

const chargebee = new Chargebee(conf: Config): ChargebeeType;

The main client. Config requires site and apiKey. Optional fields include timeout (ms), retryConfig, enableDebugLogs, userAgentSuffix, and a custom httpClient. All API resources (chargebee.customer, chargebee.subscription, etc.) are available as methods on the instance after construction.

RequestWrapper

import { RequestWrapper } from './RequestWrapper.js';

new RequestWrapper(args: IArguments, apiCall: ResourceType, envArg: EnvType): RequestWrapper
// Usage:
const rw = new RequestWrapper(arguments, apiCall, env);
await rw.request();

Wraps a single API call with retry logic, header injection, and idempotency key support. You typically do not instantiate this directly - createChargebee wires it automatically via _createApiFunc. Use it directly only when building custom resource extensions.

Config / RetryConfig (types)

import type { Config, RetryConfig } from 'chargebee';

const conf: Config = {
  site: 'mysite',
  apiKey: 'sk_live_xxx',
  retryConfig: {
    enabled: true,
    maxRetries: 3,
    delayMs: 500,
    retryOn: [429, 503],
  },
  timeout: 30000,
  enableDebugLogs: false,
};

Config is the initialization shape passed to the Chargebee constructor. RetryConfig controls automatic retry behavior: which HTTP status codes trigger a retry, how many retries, and the base delay. Both types are exported from types.d.ts.

WebhookHandler / createDefaultHandler

import { WebhookHandler } from './resources/webhook/handler.js';

const handler = new WebhookHandler({ username: 'u', password: 'p' });
// Or via the client instance:
const handler = chargebee.webhooks.createHandler({ username: 'u', password: 'p' });

WebhookHandler processes incoming Chargebee webhook HTTP requests: it validates Basic Auth credentials, parses the JSON body, and dispatches to registered event-type handlers. createDefaultHandler() reads credentials from environment variables automatically.

Working examples

Scenario - Create a customer and retrieve it

Basic async/await usage with error handling. The API call returns a typed response object.

import Chargebee from 'chargebee';

const chargebee = new Chargebee({
  site: process.env.CHARGEBEE_SITE!,
  apiKey: process.env.CHARGEBEE_API_KEY!,
});

async function run() {
  try {
    const { customer } = await chargebee.customer.create({
      email: 'alice@example.com',
      first_name: 'Alice',
      last_name: 'Example',
    });
    console.log('Created:', customer.id);

    const retrieved = await chargebee.customer.retrieve(customer.id);
    console.log('Retrieved:', retrieved.customer.email);
  } catch (err) {
    console.error('Chargebee error:', err);
  }
}

run();

Scenario - Paginate through all subscriptions

Uses next_offset from list responses to walk all pages.

import Chargebee from 'chargebee';

const chargebee = new Chargebee({
  site: process.env.CHARGEBEE_SITE!,
  apiKey: process.env.CHARGEBEE_API_KEY!,
});

async function getAllSubscriptions() {
  const all: unknown[] = [];
  let offset: string | undefined;

  do {
    const resp = await chargebee.subscription.list({
      limit: 100,
      offset,
      status: { is: 'active' },
    });
    resp.list.forEach((entry: any) => all.push(entry.subscription));
    offset = resp.next_offset;
  } while (offset);

  console.log(`Total active subscriptions: ${all.length}`);
  return all;
}

Scenario - Handle a webhook in Express

Wire WebhookHandler into an Express route. The handler validates Basic Auth, parses the event, and dispatches.

import express, { Request, Response } from 'express';
import Chargebee from 'chargebee';

const chargebee = new Chargebee({
  site: process.env.CHARGEBEE_SITE!,
  apiKey: process.env.CHARGEBEE_API_KEY!,
});

// createHandler uses explicit credentials; or rely on env vars via chargebee.webhooks
const webhookHandler = chargebee.webhooks.createHandler({
  username: process.env.CHARGEBEE_WEBHOOK_USERNAME!,
  password: process.env.CHARGEBEE_WEBHOOK_PASSWORD!,
});

const app = express();
app.use('/webhooks/chargebee', express.raw({ type: 'application/json' }));

app.post('/webhooks/chargebee', async (req: Request, res: Response) => {
  try {
    await webhookHandler.handleRequest(req, res);
  } catch (err) {
    res.status(400).send('Webhook error');
  }
});

app.listen(3000);

Scenario - Enable retries with custom config

Pass retryConfig at construction to automatically retry on rate-limits and transient errors.

import Chargebee from 'chargebee';
import type { Config } from 'chargebee';

const config: Config = {
  site: process.env.CHARGEBEE_SITE!,
  apiKey: process.env.CHARGEBEE_API_KEY!,
  retryConfig: {
    enabled: true,
    maxRetries: 4,
    delayMs: 1000,
    retryOn: [429, 503],
  },
  enableDebugLogs: true,
};

const chargebee = new Chargebee(config);

const result = await chargebee.invoice.list({ limit: 10 });
console.log(result.list.length, 'invoices');

File walkthrough

• net/ClientInterface.ts - Defines the HttpClientInterface contract that any HTTP backend must implement.
• net/FetchClient.ts - Default implementation using the global fetch API; works in Node 18+, Deno, Bun, and edge runtimes.
• resources/api_endpoints.ts - Registers all Chargebee resource endpoints with their HTTP method, URL prefix, and parameter metadata.
• resources/webhook/auth.ts - Basic Auth validation logic for incoming webhook requests.
• resources/webhook/content.ts - Parses and types the raw webhook request body.
• resources/webhook/errors.ts - Error types specific to webhook processing failures.
• resources/webhook/eventType.ts - Enumeration of all Chargebee webhook event type strings.
• resources/webhook/handler.ts - WebhookHandler class and createDefaultHandler factory; top-level webhook integration surface.
• RequestWrapper.ts - Executes API calls with retries, idempotency headers, and response normalization.
• asyncApiSupport.ts - Polling loop for Chargebee async export jobs; used by _waitForExport.
• chargebeeError.ts - ChargebeeError class that wraps API error payloads and response headers.
• coreCommon.ts - Shared handleResponse and throwError utilities for HTTP response parsing.
• createChargebee.ts - Assembles the full Chargebee client class with resources and webhook namespace.
• environment.ts - Defaults: API host suffix, protocol, port, timeouts, etc.
• filter.ts - Serializes filter objects (e.g. { is: 'active' }) into Chargebee query parameter format.
• types.d.ts - All shared TypeScript type definitions exported by the SDK.
• util.ts - Internal helpers: deep extend, isArray, isObject, URL builders, UUID generation.

Common pitfalls and fixes

• Node.js < 18: fetch is not available globally; upgrade to Node 18+ or polyfill globalThis.fetch before importing.
• ESM/CJS interop: The package ships both .cjs and .esm entry points; if you see ERR_REQUIRE_ESM, switch your project to "type": "module" or use the .cjs entry explicitly.
• Missing .js extensions in imports: TypeScript Node16 module resolution requires explicit .js extensions in relative imports; do not strip them when editing source files.
• Webhook Basic Auth not validated: createDefaultHandler() silently skips auth if CHARGEBEE_WEBHOOK_USERNAME/CHARGEBEE_WEBHOOK_PASSWORD are unset; always pass explicit credentials in production via createHandler({ username, password }).
• retryConfig not deep-merged: Partial retryConfig objects are merged with extend(true, ...) so unset fields fall back to defaults; do not assume enabled: true is the default - set it explicitly.
• apiKey leaked in logs: enableDebugLogs: true may log full request headers including the Authorization header; disable it in production environments.

Vibe-coding prompt template

I have dropped the Chargebee Node.js SDK source into `src/chargebee/` of my project.
The USAGE.md file is at `src/chargebee/USAGE.md`.
The upstream package is `user@example.com`.

Please help me integrate this SDK into my project step by step:

1. Read USAGE.md and the source files in `src/chargebee/` to understand all available exports.
2. Install any required dependencies listed in USAGE.md.
3. Create a `src/lib/chargebeeClient.ts` singleton that initializes the Chargebee client
   using environment variables CHARGEBEE_SITE and CHARGEBEE_API_KEY, with retry enabled.
4. Add a webhook handler route to my Express app at POST /webhooks/chargebee that uses
   WebhookHandler with credentials from CHARGEBEE_WEBHOOK_USERNAME and CHARGEBEE_WEBHOOK_PASSWORD.
5. Write a helper function that lists all active subscriptions using pagination (next_offset).
6. Show me how to handle ChargebeeError and log the api_error_code and http_status_code.
7. Only use imports and symbols that actually exist in `src/chargebee/` - do not invent APIs.

License and credit

The upstream source is published by Chargebee under the MIT License. See source/LICENSE if present, or refer to the npm package page and GitHub repository for full license text. This block redistributes user@example.com unmodified.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Paddle Billing Node.js SDK for Server-Side Apps

SaaS, AI & Subscription Products

Free