Node.js SDK

The official Chargebee Node.js SDK provides a convenient way to interact with the Chargebee API from your Node.js, Deno, Bun, or Edge runtime applications.

Installation

Requirements

Node.js 18 or later
Also supports Deno, Bun, Cloudflare Workers, and Edge Runtimes (Vercel Edge, Netlify Edge Functions)

Quick Start

Create a Resource

List & Pagination

Use filtering and offset / next_offset for pagination:

Idempotent Requests

Pass an idempotency key as a header in the second argument:

Error Handling

Webhooks

The SDK provides multiple approaches for handling webhooks.

Instance Handler

Set CHARGEBEE_WEBHOOK_USERNAME and CHARGEBEE_WEBHOOK_PASSWORD environment variables for automatic Basic Auth:

Factory Handler

Manual Parsing

Retry & Rate Limits

Retries are disabled by default. Enable with retryConfig:

Rate-limited responses (HTTP 429) are automatically retried after the Retry-After duration.

OpenTelemetry

The Node.js SDK includes a built-in OpenTelemetry adapter at chargebee/telemetry/otel. Import the default adapter and pass it on client initialization — no custom adapter code required:

Install @opentelemetry/api (and configure your OTLP exporter via OTEL_* env vars) in your application. See OpenTelemetry integration for span attributes, instrumentation setup, and custom adapter options.

Migration Guide

If upgrading from v2 to v3, see the migration guide.