# Node.js SDK[](#nodejs-sdk)

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


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[](#installation)

**npm**

```bash
npm install chargebee
```

**pnpm**

```bash
pnpm add chargebee
```

**yarn**

```bash
yarn add chargebee
```

**bun**

```bash
bun add chargebee
```

**deno**

```bash
deno add npm:chargebee
```

## Requirements[](#requirements)

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

## Quick Start[](#quick-start)

## Create a Resource[](#create-a-resource)

## List & Pagination[](#list-pagination)

Use filtering and `offset` / `next_offset` for pagination:

## Idempotent Requests[](#idempotent-requests)

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

## Error Handling[](#error-handling)

## Webhooks[](#webhooks)

The SDK provides multiple approaches for handling webhooks.

### Instance Handler[](#instance-handler)

Set `CHARGEBEE_WEBHOOK_USERNAME` and `CHARGEBEE_WEBHOOK_PASSWORD` environment variables for automatic Basic Auth:

### Factory Handler[](#factory-handler)

### Manual Parsing[](#manual-parsing)

## Retry & Rate Limits[](#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[](#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](/docs/api/opentelemetry) for span attributes, instrumentation setup, and custom adapter options.

## Migration Guide[](#migration-guide)

If upgrading from v2 to v3, see the [migration guide](https://github.com/chargebee/chargebee-node/wiki/Migration-guide-for-v3).

## Links[](#links)

-   [GitHub Repository](https://github.com/chargebee/chargebee-node)
-   [npm Package](https://www.npmjs.com/package/chargebee)
-   [API Reference](/docs/api/getting-started)