chargebee-node

KO | EN

gitlite — search

#python #react #typescript #llm #golang #go #android #machine-learning #docker #cli #vue #mcp #openai #open-source

(★ 61)

Node.js library for the Chargebee API.

chargebee-node Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Chargebee Node.js / TypeScript Client Library

> [!NOTE]
> [![Join Discord](https://img.shields.io/badge/Discord-Early%20Access-blue?logo=discord&logoColor=white)](https://discord.gg/gpsNqnhDm2)
>
> We are trialing a Discord server for developers building with Chargebee. Limited spots are open on a first-come basis. Join [here](https://discord.gg/S3SXDzXHAg) if interested.

> [!TIP]
> If you are using [Next.js](https://nextjs.org/) or [Express](https://expressjs.com/), check out [chargebee-init](https://www.npmjs.com/package/chargebee-init) to get started quickly with the adapters for these frameworks. Learn more about it in this [tutorial](https://www.chargebee.com/tutorials/chargebee-init-nextjs-integration/).

- 📘 For a complete reference of available APIs, check out our [API Documentation](https://apidocs.chargebee.com/docs/api/?lang=node).  
- 🧪 To explore and test API capabilities interactively, head over to our [API Explorer](https://api-explorer.chargebee.com).

If you're upgrading from an older version of [`chargebee-typescript`](https://www.npmjs.com/package/chargebee-typescript) or [`chargebee`](https://www.npmjs.com/package/chargebee/v/2.40.0), please refer to the [Migration Guide](https://github.com/chargebee/chargebee-node/wiki/Migration-guide-for-v3).

## Requirements

Node.js 18 or higher.

## Runtime Support

This SDK supports multiple JavaScript runtimes:

- **Node.js** 18+
- **Deno**
- **Bun**
- **Cloudflare Workers**
- **Edge Runtimes** (e.g., Vercel Edge, Netlify Edge Functions)

## Installation

Install the library with npm:

```sh
npm install chargebee
```
With pnpm:
```sh
pnpm add chargebee
```

With yarn:
```sh
yarn add chargebee
```

With bun:
```sh
bun add chargebee
```

With deno:
```sh
deno add npm:chargebee
```

## Usage

The package needs to be configured with your site's API key, which is available under Configure Chargebee Section. Refer [here](https://www.chargebee.com/docs/2.0/api_keys.html) for more details.

If you're using ESM / TypeScript:

```typescript
import Chargebee from 'chargebee';

const chargebee = new Chargebee({
  site: "{{site}}",
  apiKey: "{{api-key}}",
});
```

Or using Common JS module system:

```javascript
const Chargebee = require('chargebee');

const chargebee = new Chargebee({
  site: "{{site}}",
  apiKey: "{{api-key}}",
});
```

### Using Deno:

```typescript
import Chargebee from "npm:chargebee";

const chargebee = new Chargebee({
  site: "{{site}}",
  apiKey: "{{api-key}}",
});

const response = await chargebee.customer.list();
console.log(response);
```

### Using Bun:

```typescript
import Chargebee from "chargebee";

const chargebee = new Chargebee({
  site: "{{site}}",
  apiKey: "{{api-key}}",
});

const response = await chargebee.customer.list();
console.log(response);
```

### Using Async / Await

```typescript
try {
  const { customer } = await chargebee.customer.create({
    email: "john@test.com"
    // other params
  });
} catch (err) {
  // handle error
}
```

### Request parameter validation (Zod)

When `enableValidation` is set to `true`, the SDK validates parameters for **every** API request against Zod schemas **before** the HTTP call is made. If you omit the params object on a call, it is validated as `{}`. This is **off by default**. Schemas are included for API actions that support them; actions without a bundled schema behave as usual.

```typescript
import Chargebee, { ChargebeeZodValidationError } from 'chargebee';

const chargebee = new Chargebee({
  site: '{{site}}',
  apiKey: '{{api-key}}',
  enableValidation: true,
});

try {
  await chargebee.customer.create({
    id: 'a'.repeat(100),
    auto_collection: 'invalid',
  });
} catch (err) {
  if (err instanceof ChargebeeZodValidationError) {
    console.error(err.message);
    console.error(err.actionName);
    console.error(err.zodError.issues);
  } else {
    throw err;
  }
}
```

Invalid parameters produce a `ChargebeeZodValidationError`. The error message lists every problem (field path and message). You can also inspect `actionName` (the API action, for example `create`) and `zodError` (Zod’s `ZodError`, including `issues`) for structured handling.

**Example message:**

```text
ChargebeeZodValidationError: [Chargebee] Validation failed for 'create': id: Too big: expected string to have <=50 characters; auto_collection: Invalid option: expected one of "on"|"off"
```

The same `ChargebeeZodValidationError` shape applies to any action with a schema when parameters are invalid (for example bad filters or limits on `list`).

### Using filters in the List API

For pagination, `offset` is the parameter that is being used. The value used for this parameter must be the value returned for `next_offset` parameter in the previous API call.

```typescript
async function getAllCustomers() {
  const allCustomers: Customer[] = [];
  let offset: string | undefined = undefined;

do {
    const listCustomersReponse = await chargebee.customer.list({
      limit: 2,
      offset,
      first_name: {
        is: "John"
      }
    });

const customers = listCustomersReponse.list.map(
      (object) => object.customer
    );
    
    allCustomers.push(...customers);
    offset = listCustomersReponse.next_offset;
  } while (offset);

console.log(allCustomers);
}
```

### Using custom headers and custom fields

```typescript
const { customer } = await chargebee.customer.create(
  {
    email: "john@test.com",
    cf_host_url: "http://xyz.com" // `cf_host_url` is a custom field in Customer object
  },
  {
    "chargebee-event-email": "all-disabled" // To disable webhooks
  }
);
```

### Creating an idempotent request

[Idempotency keys](https://apidocs.chargebee.com/docs/api/idempotency?prod_cat_ver=2) are passed along with request headers to allow a safe retry of POST requests.

```typescript
const { customer, isIdempotencyReplayed } = await chargebee.customer.create(
  { email: "john@test.com" },
  {
    "chargebee-idempotency-key": "eBs7iOFQuR7asUKHfddyxDDerOuF1JtFrLmDI" // Add idempotency key
  }
);
console.log("isIdempotencyReplayed: ", isIdempotencyReplayed);
```

### Creating multiple instances of Chargebee for different sites

```typescript
const chargebeeSiteUS = new Chargebee({
  apiKey: "{api-key}",
  site: "my-site-us"
});

const chargebeeSiteEU = new Chargebee({
  apiKey: "{api-key}",
  site: "my-site-eu"
});
```

### Handle webhooks

Use the webhook handlers to parse and route webhook payloads from Chargebee with full TypeScript support.

#### Quick Start: Using the instance `webhooks` handler

The simplest way to handle webhooks is using the `webhooks` property on your initialized Chargebee client:

```typescript
import express from 'express';
import Chargebee, {
  WebhookEventType,
  AuthenticationError,
  PayloadValidationError,
  PayloadParseError,
} from 'chargebee';

const chargebee = new Chargebee({
  site: '{{site}}',
  apiKey: '{{api-key}}',
});

const app = express();
app.use(express.json());

// ⚠️ Register listeners once at startup, not inside request handlers
chargebee.webhooks.on(WebhookEventType.SubscriptionCreated, async ({ event, response }) => {
  console.log(`Subscription created: ${event.id}`);
  const subscription = event.content.subscription;
  console.log(`Customer: ${subscription.customer_id}`);
  response?.status(200).send('OK');
});

chargebee.webhooks.on('error', (error, { response }) => {
  if (error instanceof AuthenticationError) {
    response?.status(401).send('Unauthorized');
  } else if (error instanceof PayloadValidationError || error instanceof PayloadParseError) {
    response?.status(400).send('Bad Request');
  } else {
    console.error('Webhook error:', error.message);
    response?.status(500).send('Internal Server Error');
  }
});

app.post('/chargebee/webhooks', async (req, res) => {
  await chargebee.webhooks.handle({
    body: req.body,
    headers: req.headers,
    request: req,
    response: res,
  });
});

app.listen(8080);
```

**Auto-configured Basic Auth:** The `webhooks` handler automatically configures Basic Auth validation if the following environment variables are set:

- `CHARGEBEE_WEBHOOK_USERNAME` - The expected username
- `CHARGEBEE_WEBHOOK_PASSWORD` - The expected password

When both are present, incoming webhook requests will be validated against these credentials.

#### Creating typed webhook handlers

For more control or multiple webhook endpoints, use `chargebee.webhooks.createHandler()`:

```typescript
import express, { Request, Response } from 'express';
import Chargebee, {
  WebhookEventType,
  basicAuthValidator,
  AuthenticationError,
  PayloadValidationError,
  PayloadParseError,
} from 'chargebee';

const chargebee = new Chargebee({
  site: '{{site}}',
  apiKey: '{{api-key}}',
});

const app = express();
app.use(express.json());

// Create a typed handler for Express
const handler = chargebee.webhooks.createHandler<Request, Response>();

// Optional: Add request validator (e.g., Basic Auth)
handler.requestValidator = basicAuthValidator((username, password) => {
  return username === 'admin' && password === 'secret';
});

// ⚠️ Register event listeners once at startup, not inside request handlers
handler.on(WebhookEventType.SubscriptionCreated, async ({ event, response }) => {
  console.log(`Subscription created: ${event.id}`);
  const subscription = event.content.subscription;
  console.log(`Customer: ${subscription.customer_id}`);
  console.log(`Plan: ${subscription.plan_id}`);
  response?.status(200).send('OK');
});

handler.on(WebhookEventType.PaymentSucceeded, async ({ event, response }) => {
  console.log(`Payment succeeded: ${event.id}`);
  const transaction = event.content.transaction;
  const customer = event.content.customer;
  console.log(`Amount: ${transaction.amount}, Customer: ${customer.email}`);
  response?.status(200).send('OK');
});

handler.on('error', (error, { response }) => {
  if (error instanceof AuthenticationError) {
    response?.status(401).send('Unauthorized');
  } else if (error instanceof PayloadValidationError || error instanceof PayloadParseError) {
    response?.status(400).send('Bad Request');
  } else {
    console.error('Webhook error:', error.message);
    response?.status(500).send('Internal Server Error');
  }
});

app.post('/chargebee/webhooks', async (req, res) => {
  await handler.handle({
    body: req.body,
    headers: req.headers,
    request: req,
    response: res,
  });
});

app.listen(8080);
```

#### Low-level: Parse and handle events manually

For more control, you can parse webhook events manually:

```typescript
import express from 'express';
import Chargebee, { type WebhookEvent, WebhookEventType } from 'chargebee';

const app = express();
app.use(express.json());

app.post('/chargebee/webhooks', async (req, res) => {
  try {
    const event = req.body as WebhookEvent;

switch (event.event_type) {
      case WebhookEventType.SubscriptionCreated: {
        // Cast to specific event type for proper content typing
        const typedEvent = event as WebhookEvent<WebhookEventType.SubscriptionCreated>;
        const subscription = typedEvent.content.subscription;
        console.log('Subscription created:', subscription.id);
        break;
      }

case WebhookEventType.PaymentSucceeded: {
        const typedEvent = event as WebhookEvent<WebhookEventType.PaymentSucceeded>;
        const transaction = typedEvent.content.transaction;
        console.log('Payment succeeded:', transaction.amount);
        break;
      }

default:
        console.log('Unhandled event type:', event.event_type);
    }

res.status(200).send('OK');
  } catch (err) {
    console.error('Error processing webhook:', err);
    res.status(500).send('Error processing webhook');
  }
});

app.listen(8080);
```

#### Responding to Webhooks

> ⚠️ **Important:** Always send an HTTP response from your webhook handlers. If you don't respond with a 2xx status, Chargebee will retry the webhook, potentially causing duplicate processing.

**Respond with 200** to acknowledge receipt:

```typescript
handler.on(WebhookEventType.SubscriptionCreated, async ({ event, response }) => {
  await provisionAccess(event.content.subscription);
  response?.status(200).json({ received: true });
});
```

**Respond with 5xx** so Chargebee retries on failure:

```typescript
handler.on(WebhookEventType.PaymentSucceeded, async ({ event, response }) => {
  try {
    await recordPayment(event.content.transaction);
    response?.status(200).send('OK');
  } catch (err) {
    response?.status(500).json({ error: 'Processing failed' });
  }
});
```

**Access request context** (headers, middleware data):

```typescript
handler.on(WebhookEventType.CustomerCreated, async ({ event, request, response }) => {
  const tenantId = (request as any)?.tenant?.id;
  await createCustomerForTenant(tenantId, event.content.customer);
  response?.status(200).send('OK');
});
```

#### Handling Unhandled Events and Errors

The webhook handler provides specific error classes for different failure scenarios:

- **`AuthenticationError`** - Authentication failed (missing/invalid credentials)
- **`PayloadValidationError`** - Invalid webhook payload structure (missing required fields)
- **`PayloadParseError`** - Failed to parse JSON body

```typescript
import {
  AuthenticationError,
  PayloadValidationError,
  PayloadParseError,
} from 'chargebee';

// Handle events without registered listeners
handler.on('unhandled_event', async ({ event, response }) => {
  console.log(`Unhandled: ${event.event_type}`);
  response?.status(200).send('OK');
});

// Handle errors with appropriate HTTP status codes
handler.on('error', (error, { response }) => {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
    response?.status(401).send('Unauthorized');
  } else if (error instanceof PayloadValidationError) {
    console.error('Invalid payload:', error.message);
    response?.status(400).send('Bad Request');
  } else if (error instanceof PayloadParseError) {
    console.error('Failed to parse JSON:', error.message);
    response?.status(400).send('Bad Request');
  } else {
    console.error('Unknown error:', error.message);
    response?.status(500).send('Internal Server Error');
  }
});
```

### Processing Webhooks - API Version Check

An attribute `api_version` is added to the [Event](https://apidocs.chargebee.com/docs/api/events) resource, which indicates the API version based on which the event content is structured. In your webhook servers, ensure this `api_version` is the same as the [API version](https://apidocs.chargebee.com/docs/api#versions) used by your webhook server's client library.

### Retry Handling

Chargebee's SDK includes built-in retry logic to handle temporary network issues and server-side errors. This feature is **disabled by default** but can be **enabled when needed**.

#### Key features include:

- **Automatic retries for specific HTTP status codes**: Retries are automatically triggered for status codes `500`, `502`, `503`, and `504`.
- **Exponential backoff**: Retry delays increase exponentially to prevent overwhelming the server.
- **Rate limit management**: If a `429 Too Many Requests` response is received with a `Retry-After` header, the SDK waits for the specified duration before retrying.  
  > *Note: Exponential backoff and max retries do not apply in this case.*
- **Customizable retry behavior**: Retry logic can be configured using the `retryConfig` parameter in the environment configuration.

#### Example: Customizing Retry Logic

You can enable and configure the retry logic by passing a `retryConfig` object when initializing the Chargebee environment:

```typescript
import Chargebee from 'chargebee';

const chargebee = new Chargebee({
  site: "{{site}}",
  apiKey: "{{api-key}}",
  retryConfig: {
    enabled: true, // Enable retry logic
    maxRetries: 5, // Maximum number of retries
    delayMs: 300, // Initial delay between retries in milliseconds
    retryOn: [500, 502, 503, 504], // HTTP status codes to retry on
  },
});

try {
  const { customer } = await chargebee.customer.create({
    email: "john@test.com",
  });
  console.log("Customer created:", customer);
} catch (err) {
  console.error("Request failed after retries:", err);
}
```

#### Example: Rate Limit retry logic

You can enable and configure the retry logic for rate-limit by passing a `retryConfig` object when initializing the Chargebee environment:

```typescript
import Chargebee from 'chargebee';

const chargebee = new Chargebee({
  site: "{{site}}",
  apiKey: "{{api-key}}",
  retryConfig: {
    enabled: true,
    retryOn: [429], 
  },
});

### Webhook Type Mapping
To improve type safety and gain better autocompletion when working with webhooks, you can leverage the `WebhookEvent` resource. This allows you to strongly type the event content for a particular webhook event.

#### Example

```ts
import Chargebee, { WebhookEventType, WebhookEvent } from "chargebee";

const result = await chargebeeInstance.event.retrieve("{event-id}");
const subscriptionActivatedEvent: WebhookEvent<WebhookEventType.SubscriptionActivated> = result.event;
const subscription = subscriptionActivatedEvent.content.subscription;
```

#### Notes

* `WebhookEvent<T>` provides type hinting for the event payload, making it easier to work with specific event structures.
* Use the `WebhookEventType` to specify the exact event type (e.g., `SubscriptionCreated`, `InvoiceGenerated`, etc.).
* This approach ensures you get proper IntelliSense and compile-time checks when accessing event fields.

### Custom HTTP Client

The SDK supports injecting a **custom HTTP client**, giving you full flexibility to control how API requests are made and handled. This feature is useful if you want to integrate your own networking stack, add custom logging, implement telemetry, or handle retries in a specific way.

With this enhancement, you can replace the default HTTP client with your own implementation by passing a custom client that adheres to the `HttpClientInterface` contract when initializing the Chargebee instance.

```js
const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{key}",
    httpClient: new CustomHttpClient(),
});
```

#### Notes
* Your custom client must implement the `HttpClientInterface` provided by the SDK.
* This feature is especially useful in environments with strict networking policies or where advanced observability is required.
* Example implementations are available under:

* [`/examples/customHttpClient/axiosHttpClient.ts`](./examples/customHttpClient/axiosHttpClient.ts)
  * [`/examples/customHttpClient/kyHttpClient.ts`](./examples/customHttpClient/kyHttpClient.ts)
* You may need to implement custom conversion logic when integrating third-party HTTP libraries, as their request and response formats might not directly align with the `HttpClientInterface` expected by the SDK.

These examples demonstrate how to implement and inject custom clients using `axios` and `ky`, respectively.

### 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.

`@opentelemetry/api` is an **optional peer dependency** — it is not bundled with `chargebee` and is only loaded when you import the adapter, so a plain `import 'chargebee'` stays dependency-free.

The SDK builds standardized span attributes (`ctx.startAttributes`, `result.endAttributes`) following the stable [OpenTelemetry HTTP semantic conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/) (`url.full`, `http.request.method`, `http.response.status_code`, `server.address`, `error.type`) plus Chargebee-specific `chargebee.*` attributes — use them as-is so spans render correctly in your APM and stay consistent across SDKs.

Spans are named `chargebee.{resource}.{operation}` (e.g. `chargebee.subscription.create`).

#### Quick start (built-in adapter)

```bash
npm install chargebee @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
```

Configure OpenTelemetry once at app startup. Exporting (endpoint, service name, credentials) is driven entirely by your OpenTelemetry runtime and the standard `OTEL_*` environment variables — the adapter just uses the globally registered tracer:

```typescript
// instrumentation.ts — node --require ./instrumentation.js app.js
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

new NodeSDK({
  serviceName: process.env.OTEL_SERVICE_NAME ?? 'billing-service',
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ?? 'http://localhost:4318/v1/traces',
  }),
}).start();
```

Then import the ready-to-use adapter and pass it on client initialization:

```typescript
import Chargebee from 'chargebee';
import otelDefaultAdapter from 'chargebee/telemetry/otel';

const chargebee = new Chargebee({
  site: '{{site}}',
  apiKey: '{{api-key}}',
  telemetryAdapter: otelDefaultAdapter,
});
```

That's it — every SDK call now emits a `chargebee.<resource>.<operation>` CLIENT span that attaches to the active OpenTelemetry context (or starts a root span), with W3C trace context propagated to Chargebee. Spans are exported by your own OpenTelemetry setup, so they flow to whatever backend you've configured (Datadog, Splunk, Honeycomb, Jaeger, etc.) — refer to your APM vendor's OpenTelemetry/OTLP documentation for exporter endpoints.

#### Custom adapter (advanced)

To customize behavior (different tracer name, extra attributes, a non-OpenTelemetry backend, etc.), implement `TelemetryAdapter` yourself instead of importing the built-in adapter:

```typescript
import Chargebee, {
  type TelemetryAdapter,
  type RequestTelemetryContext,
  type RequestTelemetryResult,
} from 'chargebee';
import { context, propagation, trace, SpanKind, SpanStatusCode, type Span } from '@opentelemetry/api';

class OtelTelemetryAdapter implements TelemetryAdapter<Span> {
  private readonly tracer = trace.getTracer('chargebee-node');

onRequestStart(ctx: RequestTelemetryContext, requestHeaders: Record<string, string | number>): Span {
    const span = this.tracer.startSpan(ctx.spanName, {
      kind: SpanKind.CLIENT,
      attributes: ctx.startAttributes,
    });
    propagation.inject(trace.setSpan(context.active(), span), requestHeaders);
    return span;
  }

onRequestEnd(span: Span | void, result: RequestTelemetryResult) {
    if (!span) return;
    for (const [key, value] of Object.entries(result.endAttributes)) {
      span.setAttribute(key, value);
    }
    if (result.error) {
      span.recordException(new Error(result.error.message));
      span.setStatus({ code: SpanStatusCode.ERROR, message: result.error.message });
    } else {
      span.setStatus({ code: SpanStatusCode.OK });
    }
    span.end();
  }
}

const chargebee = new Chargebee({
  site: '{{site}}',
  apiKey: '{{api-key}}',
  telemetryAdapter: new OtelTelemetryAdapter(),
});
```

## Feedback

If you find any bugs or have any questions / feedback, open an issue in this repository or reach out to us on dx@chargebee.com

## v2

Chargebee Node SDK v2 is deprecated. If you using v2, follow [this guide](https://github.com/chargebee/chargebee-node/wiki/Migration-guide-for-v3) to migrate to v3.

chargebee-node

chargebee-node Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

chargebee-node

chargebee-node Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README