This is the official Node.js library for integrating with Chargebee.
Tip
If you are using Next.js or Express, check out chargebee-init to get started quickly with the adapters for these frameworks. Learn more about it in this tutorial.
- 📘 For a complete reference of available APIs, check out our API Documentation.
- 🧪 To explore and test API capabilities interactively, head over to our API Explorer.
If you're upgrading from an older version of chargebee-typescript or chargebee, please refer to the Migration Guide.
Node.js 18 or higher.
Install the library with npm:
npm install chargebeeWith pnpm:
pnpm add chargebeeWith yarn:
yarn add chargebeeThe package needs to be configured with your site's API key, which is available under Configure Chargebee Section. Refer here for more details.
If you're using ESM / TypeScript:
import Chargebee from 'chargebee';
const chargebee = new Chargebee({
site: "{{site}}",
apiKey: "{{api-key}}",
});Or using Common JS module system:
const Chargebee = require('chargebee');
const chargebee = new Chargebee({
site: "{{site}}",
apiKey: "{{api-key}}",
});try {
const { customer } = await chargebee.customer.create({
email: "john@test.com"
// other params
});
} catch (err) {
// handle error
}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.
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);
}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
}
);Idempotency keys are passed along with request headers to allow a safe retry of POST requests.
const { customer, isIdempotencyReplayed } = await chargebee.customer.create(
{ email: "john@test.com" },
{
"chargebee-idempotency-key": "eBs7iOFQuR7asUKHfddyxDDerOuF1JtFrLmDI" // Add idempotency key
}
);
console.log("isIdempotencyReplayed: ", isIdempotencyReplayed);const chargebeeSiteUS = new Chargebee({
apiKey: "{api-key}",
site: "my-site-us"
});
const chargebeeSiteEU = new Chargebee({
apiKey: "{api-key}",
site: "my-site-eu"
});An attribute api_version is added to the Event 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 used by your webhook server's client library.
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.
- Automatic retries for specific HTTP status codes: Retries are automatically triggered for status codes
500,502,503, and504. - Exponential backoff: Retry delays increase exponentially to prevent overwhelming the server.
- Rate limit management: If a
429 Too Many Requestsresponse is received with aRetry-Afterheader, 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
retryConfigparameter in the environment configuration.
You can enable and configure the retry logic by passing a retryConfig object when initializing the Chargebee environment:
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);
}You can enable and configure the retry logic for rate-limit by passing a retryConfig object when initializing the Chargebee environment:
import Chargebee from 'chargebee';
const chargebee = new Chargebee({
site: "{{site}}",
apiKey: "{{api-key}}",
retryConfig: {
enabled: true,
retryOn: [429],
},
});
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);
}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
Chargebee Node SDK v2 is deprecated. If you using v2, follow this guide to migrate to v3.