Getting started
Chargebee provides an HTTP-based API that follows the principles of
REST. The HTTP rules followed allow simple HTTP clients like cURL to be used as
well. The URLs are resource-oriented, the request format is form-encoded, and
the responses are in JSON.
Depending on the type of operation, the endpoints use one of two HTTP methods:
-
GET
: Used for all read-only operations such as retrieving a
resource or listing a group of resources.
-
POST
: Used for all write operations. Such operations modify the
state of a resource.
A history of changes to the API is provided in the
API Changelog.
Note
Sometimes, while working with Chargebee APIs, you may see undocumented
attributes returned in the response. Such attributes should be ignored.
Early Access Program
Some features in the API are part of the Early Access Program and are
labeled "EAP," "Beta," or "Early Access." Please review the
terms and conditions
that apply to these features before using them.
Chargebee follows the REST model of exposing resources as urls. For example, subscriptions are exposed as
https://{site}.chargebee.com/api/v2/subscriptions
The Node.js client library provide a corresponding class representation of the resource. For example, subscriptions are represented by
Request
All operations specific to that resource are exposed as static methods in the corresponding
resource class. The methods accepts the input params as hash and returns a RequestWrapper object.
On that object you need to invoke the request method and pass the callback function. You could also pass the environment configuration specific to that request as an additional parameter.
Response
The response is in JSON format.
Currently Chargebee does not support any other response format.
Note: Sometimes, while working with Chargebee APIs, you may see undocumented attributes returned in the response. Such attributes should be ignored.
Sample Request
import Chargebee from "chargebee";
const chargebee = new Chargebee({
site : "{site}",
apiKey : "{site_api_key}",
});
try {
const result = await chargebee.subscription.create({
plan_id : "no_trial",
auto_collection : "off",
customer : {
first_name : "John",
last_name : "Doe",
email : "john@user.com"
},
billing_address : {
first_name : "John",
last_name : "Doe",
line1 : "PO Box 9999",
city : "Walnut",
state : "California",
zip : "91789",
country : "US"
}
});
console.log(result);
const subscription = result.subscription;
const customer = result.customer;
const card = result.card;
const invoice = result.invoice;
const unbilledCharges = result.unbilled_charges;
} catch (err) {
console.log(err);
}
import Chargebee from "chargebee";
const chargebee = new Chargebee({
site : "{site}",
apiKey : "{site_api_key}",
});
try {
const result = await chargebee.subscription.create({
plan_id : "no_trial",
auto_collection : "off",
plan_unit_price : 200,
billing_alignment_mode : "immediate"
});
console.log(result);
const subscription = result.subscription;
const customer = result.customer;
const card = result.card;
const invoice = result.invoice;
const unbilledCharges = result.unbilled_charges;
} catch (err) {
console.log(err);
}
import Chargebee from "chargebee";
const chargebee = new Chargebee({
site : "{site}",
apiKey : "{site_api_key}",
});
try {
const result = await chargebee.subscription.create({
plan_id : "no_trial",
coupon_ids : ["plan_only_coupon"],
auto_collection : "off",
addons : [
{
id : "ssl"
}]
});
console.log(result);
const subscription = result.subscription;
const customer = result.customer;
const card = result.card;
const invoice = result.invoice;
const unbilledCharges = result.unbilled_charges;
} catch (err) {
console.log(err);
}
import Chargebee from "chargebee";
const chargebee = new Chargebee({
site : "{site}",
apiKey : "{site_api_key}",
});
try {
const result = await chargebee.subscription.create({
plan_id : "no_trial",
auto_collection : "off",
cf_gender : "Male",
meta_data : '{"features":{"usage-limit":"5GB","speed-within-quota":"2MBbps","post-usage-quota":"512kbps"}}'
});
console.log(result);
const subscription = result.subscription;
const customer = result.customer;
const card = result.card;
const invoice = result.invoice;
const unbilledCharges = result.unbilled_charges;
} catch (err) {
console.log(err);
}
import Chargebee from "chargebee";
const chargebee = new Chargebee({
site : "{site}",
apiKey : "{site_api_key}",
});
try {
const result = await chargebee.subscription.create({
plan_id : "no_trial",
invoice_immediately : false,
terms_to_charge : 2,
auto_collection : "off",
addons : [
{
id : "ssl"
}]
});
console.log(result);
const subscription = result.subscription;
const customer = result.customer;
const card = result.card;
const invoice = result.invoice;
const unbilledCharges = result.unbilled_charges;
} catch (err) {
console.log(err);
}
Creates a subscription with customer information and billing details.
import Chargebee from "chargebee";
const chargebee = new Chargebee({
site : "{site}",
apiKey : "{site_api_key}",
});
try {
const result = await chargebee.subscription.create({
plan_id : "no_trial",
auto_collection : "off",
customer : {
first_name : "John",
last_name : "Doe",
email : "john@user.com"
},
billing_address : {
first_name : "John",
last_name : "Doe",
line1 : "PO Box 9999",
city : "Walnut",
state : "California",
zip : "91789",
country : "US"
}
});
console.log(result);
const subscription = result.subscription;
const customer = result.customer;
const card = result.card;
const invoice = result.invoice;
const unbilledCharges = result.unbilled_charges;
} catch (err) {
console.log(err);
}
Creates a subscription with customer information and billing details.
import Chargebee from "chargebee";
const chargebee = new Chargebee({
site : "{site}",
apiKey : "{site_api_key}",
});
try {
const result = await chargebee.subscription.create({
plan_id : "no_trial",
auto_collection : "off",
customer : {
first_name : "John",
last_name : "Doe",
email : "john@user.com"
},
billing_address : {
first_name : "John",
last_name : "Doe",
line1 : "PO Box 9999",
city : "Walnut",
state : "California",
zip : "91789",
country : "US"
}
});
console.log(result);
const subscription = result.subscription;
const customer = result.customer;
const card = result.card;
const invoice = result.invoice;
const unbilledCharges = result.unbilled_charges;
} catch (err) {
console.log(err);
}
Creates a subscription by overriding plan's default price.
import Chargebee from "chargebee";
const chargebee = new Chargebee({
site : "{site}",
apiKey : "{site_api_key}",
});
try {
const result = await chargebee.subscription.create({
plan_id : "no_trial",
auto_collection : "off",
plan_unit_price : 200,
billing_alignment_mode : "immediate"
});
console.log(result);
const subscription = result.subscription;
const customer = result.customer;
const card = result.card;
const invoice = result.invoice;
const unbilledCharges = result.unbilled_charges;
} catch (err) {
console.log(err);
}
Creates a subscription with addons and coupons.
import Chargebee from "chargebee";
const chargebee = new Chargebee({
site : "{site}",
apiKey : "{site_api_key}",
});
try {
const result = await chargebee.subscription.create({
plan_id : "no_trial",
coupon_ids : ["plan_only_coupon"],
auto_collection : "off",
addons : [
{
id : "ssl"
}]
});
console.log(result);
const subscription = result.subscription;
const customer = result.customer;
const card = result.card;
const invoice = result.invoice;
const unbilledCharges = result.unbilled_charges;
} catch (err) {
console.log(err);
}
Creates a subscription with meta data and custom fields.
import Chargebee from "chargebee";
const chargebee = new Chargebee({
site : "{site}",
apiKey : "{site_api_key}",
});
try {
const result = await chargebee.subscription.create({
plan_id : "no_trial",
auto_collection : "off",
cf_gender : "Male",
meta_data : '{"features":{"usage-limit":"5GB","speed-within-quota":"2MBbps","post-usage-quota":"512kbps"}}'
});
console.log(result);
const subscription = result.subscription;
const customer = result.customer;
const card = result.card;
const invoice = result.invoice;
const unbilledCharges = result.unbilled_charges;
} catch (err) {
console.log(err);
}
Creates a subscription with unbilled charges.
import Chargebee from "chargebee";
const chargebee = new Chargebee({
site : "{site}",
apiKey : "{site_api_key}",
});
try {
const result = await chargebee.subscription.create({
plan_id : "no_trial",
invoice_immediately : false,
terms_to_charge : 2,
auto_collection : "off",
addons : [
{
id : "ssl"
}]
});
console.log(result);
const subscription = result.subscription;
const customer = result.customer;
const card = result.card;
const invoice = result.invoice;
const unbilledCharges = result.unbilled_charges;
} catch (err) {
console.log(err);
}
Sample Response [ JSON ]
Show more...
{
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"billing_address": {
"city": "Walnut",
"country": "US",
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"object": "billing_address",
"state": "California",
"state_code": "CA",
"validation_status": "not_validated",
"zip": "91789"
},
"card_status": "no_card",
"created_at": 1517505643,
"deleted": false,
"email": "john@user.com",
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnHhSBWkkwI2Tn",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517505643000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517505643
},
"invoice": {
"adjustment_credit_notes": [],
"amount_adjusted": 0,
"amount_due": 895,
"amount_paid": 0,
"amount_to_collect": 895,
"applied_credits": [],
"base_currency_code": "USD",
"billing_address": {
"city": "Walnut",
"country": "US",
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"object": "billing_address",
"state": "California",
"state_code": "CA",
"validation_status": "not_validated",
"zip": "91789"
},
"credits_applied": 0,
"currency_code": "USD",
"customer_id": "__test__KyVnHhSBWkkwI2Tn",
"date": 1517505643,
"deleted": false,
"due_date": 1517505643,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": true,
"has_advance_charges": false,
"id": "__demo_inv__11",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 895,
"customer_id": "__test__KyVnHhSBWkkwI2Tn",
"date_from": 1517505643,
"date_to": 1519924843,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__KyVnHhSBWkkxu2Tp",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__KyVnHhSBWkkwI2Tn",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 895
},
{..}
],
"linked_orders": [],
"linked_payments": [],
"net_term_days": 0,
"new_sales_amount": 895,
"object": "invoice",
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517505643000,
"round_off_amount": 0,
"status": "payment_due",
"sub_total": 895,
"subscription_id": "__test__KyVnHhSBWkkwI2Tn",
"tax": 0,
"term_finalized": true,
"total": 895,
"updated_at": 1517505643,
"write_off_amount": 0
},
"subscription": {
"activated_at": 1517505643,
"auto_collection": "off",
"billing_period": 1,
"billing_period_unit": "month",
"created_at": 1517505643,
"currency_code": "USD",
"current_term_end": 1519924843,
"current_term_start": 1517505643,
"customer_id": "__test__KyVnHhSBWkkwI2Tn",
"deleted": false,
"due_invoices_count": 1,
"due_since": 1517505643,
"has_scheduled_changes": false,
"id": "__test__KyVnHhSBWkkwI2Tn",
"mrr": 0,
"next_billing_at": 1519924843,
"object": "subscription",
"plan_amount": 895,
"plan_free_quantity": 0,
"plan_id": "no_trial",
"plan_quantity": 1,
"plan_unit_price": 895,
"resource_version": 1517505643000,
"started_at": 1517505643,
"status": "active",
"total_dues": 895,
"updated_at": 1517505643
}
}
Client libraries
Chargebee provides the following open-source client libraries as a wrapper
around the HTTP API:
To view this API reference tailored to the programming language of your choice,
select the language in the “Library” dropdown above. Reach out to us at
dx@chargebee.com if you’d
like to request any other language bindings.
Node.js client library
Note
Select the programming language of your choice from the “Library” dropdown at the top of the page.
Installing Node Library
The library can be installed using npm
npm install chargebee
Then require the library as:
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}}",
});
Source Code
The source code for the client library is available as a public repository
at github. The
code is provided with MIT license.
So in case you need any modifications please feel free to do so. If you
think it would be useful for other users please do let us know.
LIBRARY VERSIONS
The Node client library currently supports two versions: v2 and v3. Version v2 is deprecated and will continue to receive updates and support until September 30, 2025. After this date, v2 will no longer be supported, and we encourage users to migrate to v3.
See the source code readme for more details.
Version 3:
* Latest release: 3.7.0
* Release date: 2025-05-15
Version 2:
* Latest release: 2.50.0
* Release date: 2025-05-15
Build with LLMs
You can leverage LLMs to build integrations with Chargebee. These tools streamline development, making it easier to automate and simplify workflows.
OpenAPI Specification
Chargebee supports the OpenAPI Specification to make it easier for developers to work with our APIs.
The spec is fully compliant with OpenAPI v3.0.1, enabling customers to:
- Use API development tools like Swagger and Postman
- Automate testing and documentation workflows
This is part of our commitment to providing a smoother, more efficient developer experience.
Code samples
The sample code snippets provided for the endpoints in this documentation are ready-to-test. Once you
log in and select a test site using the dropdown that appears at the top, the code samples in this documentation automatically include your API key and site data.
API testing
Chargebee provides the
Time Machine feature to help you test your integration. Once you've set up your billing configuration on the test site, you can simulate events on a hypothetical time frame to ensure everything works as expected. Ensure that you rigorously test your configuration before going live.
Additional developer resources
Check out our collection of
sample applications and related tutorials for integrating with Chargebee.