chargebee-typescript
Advanced tools
[!WARNING]
This repository contains the code for chargebee-typescript SDK which is deprecated. This will continue to receive updates till September 30, 2025. If you are using this, we request you to migrate to chargebee package by following this migration guide before September 30, 2025.
This is a server-side typescript library for integrating with Chargebee. Sign up for a Chargebee account here.
Node 8 or higher.
Install the latest version of the library with:
npm install chargebee-typescript
# or
yarn add chargebee-typescript
# or
pnpm install chargebee-typescript
The package needs to be configured with your site's API key, which is available under Configure Chargebee Section. Refer here for more details.
import { ChargeBee } from 'chargebee-typescript';
const chargebee = new ChargeBee();
chargebee.configure({
site: 'YOUR_SITE_NAME',
api_key: 'YOUR_API_KEY',
});
try {
const { customer } = await chargebee.customer
.create({
email: 'john@test.com',
// other params
})
.request();
} catch (err) {
// handle error
}
chargebee.customer
.create({
email: 'john@test.com',
// other params
})
.request()
.then((result) => {
// handle result
// access customer as result.customer;
})
.catch((err) => {
// handle error
});
chargebee.customer
.create({
email: 'john@test.com',
// other params
})
.request(function (error, result) {
if (error) {
// handle error
} else {
// handle result
}
});
import { ChargeBee, _customer } from 'chargebee-typescript';
const chargebee = new ChargeBee();
chargebee.configure({
site: 'YOUR_SITE_NAME',
api_key: 'YOUR_API_KEY',
});
const createCustomer = async () => {
const params: _customer.create_params = {
email: 'john@test.com',
first_name: 'John',
last_name: 'Doe',
};
const { customer } = await chargebee.customer.create(params).request();
console.log(customer);
};
createCustomer();
The response object returned by the request() method is generic response wrapper. You need to access the resource from it. For example,
const result = await chargebee.customer.create({ email: 'john@test.com' }).request();
console.log(result.customer);
Other resources can be accessed by the same approach. For subscription, it will be result.subscription
const result = await chargebee.subscription
.list({
/* params */
})
.request();
// A list of Subscription objects
console.log(result.list.map((obj) => obj.subscription));
Note
If you have a result (or children further down the line) and are unsure what properties are available, you can use Object.keys to get a list of available accessor properties. Using Object.keys in the previous example would yield
// ['list', 'next_offset']
console.log(Object.keys(result));
// ['1', '2', '3'], e.g. `result.list` is an array with 3 entries
console.log(Object.keys(result.list));
// ['activated_at', 'base_currency_code', ...]
// ['activated_at', 'base_currency_code', ...]
// ['activated_at', 'base_currency_code', ...]
// Which means we've reached the bottom and should have all the information available from this request
console.log(result.list.map((obj) => obj.subscription));
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.
const fetchCustomers = async (offset?: any) => {
const params: _customer.customer_list_params = {
offset,
limit: 2,
first_name: {
is: 'John',
},
};
const result = await chargebee.customer.list(params).request();
return {
customers: result.list.map((obj) => obj.customer),
next_offset: result.next_offset,
};
};
const { customers, next_offset } = fetchCustomers();
// Fetching next set of customers
fetchCustomers(next_offset);
chargebee.customer
.create({ email: 'john@test.com' })
.param({
cf_host_url: 'http://xyz.com',
})
.headers({
'chargebee-event-email': 'all-disabled', // To disable webhooks
'chargebee-request-origin-ip': '192.168.1.2',
})
.request()
.then((result) => {
const customer = result.customer;
console.log(customer.cf_host_url);
});
Idempotency keys are passed along with request headers to allow a safe retry of POST requests.
import { ChargeBee } from 'chargebee-typescript';
chargebee.customer
.create({
email: 'john@test.com',
})
.setIdempotencyKey('<<UUID>>') // Replace <<UUID>> with a unique string
.request()
.then((result) => {
const customer: typeof chargebee.customer = result.customer;
const responseHeaders = result.getResponseHeaders(); // Retrieves response headers
console.log(responseHeaders);
const idempotencyReplayedValue = result.isIdempotencyReplayed(); // Retrieves idempotency replayed header value
console.log(idempotencyReplayedValue);
});
Note: isIdempotencyReplayed() method can be accessed to differentiate between original and replayed requests.
All asynchronous errors will be available as the first argument of request() method's callback or in the form of a rejected promise. Detailed documentation on error handling is available here.
//The callback function that you provide needs to take in two arguments. The first being error object and the
//second being the response. Incase of error, the error object is passed.
chargebee.subscription
.create({
//create params...
})
.request(function (error, result) {
if (error) {
handleCreateSubscriptionError(error);
} else {
console.log(result.subscription);
}
});
function handleCreateSubscriptionError(ex) {
if (ex.type == 'payment') {
// First check for card parameters entered by the user.
// We recommend you to validate the input at the client side itself to catch simple mistakes.
if ('card[number]' == ex.param) {
// Ask your user to recheck the card number. A better way is to use
// Stripe's https://github.com/stripe/jquery.payment for validating it in the client side itself.
//}else if(<other card params> == ex.param){
//Similarly check for other card parameters entered by the user.
//....
} else {
// Verfication or processing failures.
// Provide a standard message to your user to recheck his card details or provide a different card.
// Like 'Sorry,there was a problem when processing your card, please check the details and try again'.
}
} else if (ex.type == 'invalid_request') {
// For coupons you could decide to provide specific messages by using
// the 'api_error_code' attribute in the ex.
if ('coupon' == ex.param) {
if ('resource_not_found' == ex.api_error_code) {
// Inform user to recheck his coupon code.
} else if ('resource_limit_exhausted' == ex.api_error_code) {
// Inform user that the coupon code has expired.
} else if ('invalid_request' == ex.api_error_code) {
// Inform user that the coupon code is not applicable for his plan(/addons).
} else {
// Inform user to recheck his coupon code.
}
} else {
// Since you would have validated all other parameters on your side itself,
// this could probably be a bug in your code. Provide a generic message to your users.
}
} else if (ex.type == 'operation_failed') {
// Indicates that the request parameters were right but the request couldn't be completed.
// The reasons might be "api_request_limit_exceeded" or could be due to an issue in ChargeBee side.
// These should occur very rarely and mostly be of temporary nature.
// You could ask your user to retry after some time.
} else if (ex.type == 'io_error') {
// Handle IO exceptions such as connection timeout, request timeout etc.
// You could give a generic message to the customer retry after some time.
} else {
// These are unhandled exceptions (Could be due to a bug in your code or very rarely in client library).
// The errors from ChargeBee such as authentication failures will come here.
// You could ask users contact your support.
}
}
The full documentation can be found on the Chargebee API Docs:
https://apidocs.chargebee.com/docs/api?lang=typescript
See the LICENSE file.
v2.43.0 (2024-11-27)
FAQs
A library in typescript for integrating with Chargebee.
The npm package chargebee-typescript receives a total of 56,070 weekly downloads. As such, chargebee-typescript popularity was classified as popular.
We found that chargebee-typescript demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.