{
  "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.

完全なインストールガイドと統合プロンプトは購入後に解放されます。

Paddle Billing Node.js SDK for Server-Side Apps

SaaS, AI & Subscription Products

無料