Chargebee Typescript Client Library - API V2
This is a server-side typescript library for integrating with Chargebee. Sign up for a Chargebee account here.
Requirements
Node 8 or higher.
Installation
Install the latest version of the library with:
npm install chargebee-typescript
yarn add chargebee-typescript
pnpm install chargebee-typescript
Usage
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',
});
Using Async / Await
try {
const { customer } = await chargebee.customer
.create({
email: 'john@test.com',
})
.request();
} catch (err) {
}
Using Promises
chargebee.customer
.create({
email: 'john@test.com',
})
.request()
.then((result) => {
})
.catch((err) => {
});
Using callbacks
chargebee.customer
.create({
email: 'john@test.com',
})
.request(function (error, result) {
if (error) {
} else {
}
});
Using typings
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();
Accessing the response object
The response object returned by the request()
method is generic response wrapper. You need to access the resource from it. For example,
- To access customer object.
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({
})
.request();
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
console.log(Object.keys(result));
console.log(Object.keys(result.list));
console.log(result.list.map((obj) => obj.subscription));
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.
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();
fetchCustomers(next_offset);
Using custom headers and custom fields:
chargebee.customer
.create({ email: 'john@test.com' })
.param({
cf_host_url: 'http://xyz.com',
})
.headers({
'chargebee-event-email': 'all-disabled',
'chargebee-request-origin-ip': '192.168.1.2',
})
.request()
.then((result) => {
const customer = result.customer;
console.log(customer.cf_host_url);
});
Create an idempotent request
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>>')
.request()
.then((result) => {
const customer: typeof chargebee.customer = result.customer;
const responseHeaders = result.getResponseHeaders();
console.log(responseHeaders);
const idempotencyReplayedValue = result.isIdempotencyReplayed();
console.log(idempotencyReplayedValue);
});
Note: isIdempotencyReplayed()
method can be accessed to differentiate between original and replayed requests.
Error handling:
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.
chargebee.subscription
.create({
})
.request(function (error, result) {
if (error) {
handleCreateSubscriptionError(error);
} else {
console.log(result.subscription);
}
});
function handleCreateSubscriptionError(ex) {
if (ex.type == 'payment') {
if ('card[number]' == ex.param) {
} else {
}
} else if (ex.type == 'invalid_request') {
if ('coupon' == ex.param) {
if ('resource_not_found' == ex.api_error_code) {
} else if ('resource_limit_exhausted' == ex.api_error_code) {
} else if ('invalid_request' == ex.api_error_code) {
} else {
}
} else {
}
} else if (ex.type == 'operation_failed') {
} else if (ex.type == 'io_error') {
} else {
}
}
Documentation
The full documentation can be found on the Chargebee API Docs:
https://apidocs.chargebee.com/docs/api?lang=typescript
License
See the LICENSE file.