# API Reference

Chargebee.js API can help you to handle more advanced use cases,

  • Setting checkout and portal callbacks
  • Modifying the plan quantity dynamically
  • Adding / removing addons on demand
  • Prefilling customer information and shipping information in the checkout
This reference is for Drop-in script based integration. If you are integrating using API use this reference instead.

# Chargebee object

# getInstance

This function will return chargebee instance object that can help you with some advanced customizations.

# Syntax

Chargebee.getInstance();
1

# Return value

chargebee instance object

# registerAgain

This function is used to rebind all the events attached. Use this function if a new element inserted dynamically after page load.

# Syntax

Chargebee.registerAgain();
1

# Chargebee instance object

Chargebee instance object is used to set callbacks for checkout and self-serve portal, and to fetch cart and product data related to checkout.To ensure that you get all the callbacks which you set, do whitelist your domain in Chargebee. You can allowlist your domain here, Settings > Configure Chargebee >Checkout & Self-Serve Portal Settings > Configuration > Advanced Settings > Add domains

# setCheckoutCallbacks

You can use this function to set callbacks with respect to checkout.

# Syntax

cbInstance.setCheckoutCallbacks(setterFunction);
1

# Parameters

setterFunction
Function
Arguments - Hide
cart
Cart Object
Return type
callbacks
Object Hide properties
loaded
Function
This function will be called once the checkout page is loaded.
error
Function
This function will be called if the promise returned from the hostedPage function rejects an error.
success
Function
This function will be called once the checkout is successful.
Arguments - Hide
hostedPageId
String
Hosted page token.
close
Function
This function will be called once the checkout is closed by the end user.
step
Function
This function will be called everytime a user navigates from one step to another during checkout. You can send the step value to different tracking services for identiyfing checkout drop-off.
Arguments - Hide
currentStep
String
Current step in checkout.
resize
Function
This function is invoked whenever the height of the embedded checkout page changes due to interactions within the page. The callback receives the new height, allowing the iframe size in the parent page to be adjusted accordingly.
trackCustom
String
Custom event name.
subscriptionExtended
Function
This function will be called when an end customer extends their subscription.
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
Subscription ID

# Example

cbInstance.setCheckoutCallbacks(function(cart) {
  // you can define a custom callbacks based on cart object
  return {
    loaded: function() {
      console.log("checkout opened");
    },
    close: function() {
      console.log("checkout closed");
    },
    success: function(hostedPageId) {
      console.log("Checkout success. ID:", data.id);
    },
    step: function(value) {
      // value -> which step in checkout
      console.log("Checkout step:", value);
    },
    resize: function(value) {
      console.log("Checkout page height:", value);
    }
  }
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# setPortalCallbacks

You can use this function to set callbacks with respect to Self-serve portal.

# Syntax

Chargebee.setPortalCallbacks(callbacks);
1

# Parameters

callbacks
Object Hide properties
loaded
Function
This function will be called once the portal is loaded.
close
Function
This function will be called once the portal is closed by the end user.
visit
Function
This function will be called everytime an user visits a section in the customer portal.
Arguments - Hide
sectionType
String
paymentSourceAdd
Function
This function will be called whenever a new payment source is added in portal
paymentSourceUpdate
Function
This function will be called whenever a payment source is updated in portal
paymentSourceRemove
Function
This function will be called whenever a payment source is removed from portal.
subscriptionChanged
Function
This function will be called whenever a subscription is changed.
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
Subscription ID
subscriptionCustomFieldsChanged
Function
This function will be called whenever a subscription custom fields are changed.
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
Subscription ID
subscriptionCancelled
Function
This function will be called when a subscription is canceled.
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
Subscription ID
subscriptionResumed
Function
This function will be called when a subscription is resumed.
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
Subscription ID
subscriptionPaused
Function
This function will be called when a subscription is paused.
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
Subscription ID
scheduledPauseRemoved
Function
This function will be called when a subscription that is scheduled for pause is removed.
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
Subscription ID
scheduledCancellationRemoved
Function
This function will be called when the schedule to cancel a subscription is removed.
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
Subscription ID
subscriptionReactivated
Function
This function will be called when an end customer reactivates their canceled subscription.
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
Subscription ID
subscriptionExtended
Function
This function will be called when an end customer extends their subscription.
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
Subscription ID

# Example

cbInstance.setPortalCallbacks({
  close: function() {
    console.log("closed");
  },
  visit: function(value) {
    // value -> which page in checkout/portal
    console.log(value);
  }
});
1
2
3
4
5
6
7
8
9

# getCart

This function retrieves the Cart object.

# Syntax

var cart = cbInstance.getCart();
1

# Return value

Cart object

# initializeProduct

This function initializes the Product object.

# Syntax

var product = cbInstance.initializeProduct(planId, planQuantity);
1

# Parameters

planId
String Required
Unique identifier for the plan / item price.
planQuantity
number
Quantity of the plan in number, if applicable.

# Return value

Product object

# Examples

var product = cbInstance.initializeProduct('test-plan');
1

# getProduct

This function retrieves the Product object associated with a checkout button.

# Syntax

var product = cbInstance.getProduct(checkoutButtonElement);
1

# Return value

Product object

# Examples

var checkoutButtonElement = document.querySelectorAll("[data-cb-type=checkout]")[0];
var product = cbInstance.getProduct(checkoutButtonElement);
1
2

# Cart object

Cart object is meant to provide advanced control while using Drop-in script to dynamically change customer details and also dynamic change product information with the help of Product object. It contains customer related information such as shipping, billing information and product information.

# setCustomer

Use this function to set customer related information. This information is passed and pre-filled in checkout automatically. Customer level custom fields can also be passed.

# Syntax

cart.setCustomer(customer);
1

# Parameters

customer
Object Hide properties
Customer details.
first_name
String
Customer first name.
last_name
String
Customer last name.
locale
String
Locale code in ISO 639-1 format (en, fr). By default, `en` will be used. Learn more about supported locales by Chargebee.
company
String
Company name.
phone
String
Customer phone number.
email
String
Customer mail ID.
billingAddress
Object Hide properties
first_name
String
First name
last_name
String
Last name
company
String
Company name
phone
String
Phone number.
email
String
Email ID
line1
String
Address line 1
line2
String
Address line 2
city
String
City
state
String
State name
state_code
String
State code
country
String
Country code
zip
String
Zip/Postal code

# *Example

const cbInstance = Chargebee.getInstance();
const cart = cbInstance.getCart();
const customer = {
    first_name: "John", 
    last_name: "Smith", 
    locale: "it",
    billing_address: {
        first_name: "John", 
        last_name: " Smith", 
        line1: "132, My Street", 
        line2: "Kingston, New York",
        state_code: "NY",
        country: "US",
        zip: "12401"
    }
};

// Setting custom fields
customer["cf_about_myself"] = "This is short description"
cart.setCustomer(customer);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# setShippingAddress

Use this function to set shipping information. This information is passed and pre-filled in checkout automatically.

# Syntax

cart.setShippingAddress(shippingAddress);
1

# Parameters

shippingAddress
Object Hide properties
first_name
String
First name
last_name
String
Last name
company
String
Company name
phone
String
Phone number.
email
String
Email ID
line1
String
Address line 1
line2
String
Address line 2
city
String
City
state
String
State name
state_code
String
State code
country
String
Country code
zip
String
Zip/Postal code

# Examples

var cart = cbInstance.getCart();
var shippingAddress = {first_name: "", last_name: "", company: "", phone: "", line1: "", line2: ""};
cart.setShippingAddress(shippingAddress);
1
2
3

# Product object

Product object is used to dynamically change plan quantity, addons, and coupons.

# addAddon

# Syntax

product.addAddon(addon);
1

# Parameters

addon
addon
Object Hide properties
id
String Required
Addon id
quantity
Number
Addon quantity
quantity_in_decimal
String
Addon quantity in decimal
String
Addon id

# Example

product.addAddon({id: "addon_1", quantity: 2});
product.addAddon("addon_1");
1
2

# Syntax

product.removeAddon(addon);
1

# Parameters

addon
addon
Object Hide properties
id
String Required
Addon id
quantity
Number
Addon quantity
quantity_in_decimal
String
Addon quantity in decimal
String
Addon id

# Example

product.removeAddon({id: "addon_1", quantity: 2});
product.removeAddon("addon_1");
1
2

# setPlanQuantity

Use this to set a plan quantity.

# Syntax

product.setPlanQuantity(planQuantity);
1

# setAddons

Use this to dynamically set a list of addons.

# Syntax

product.setAddons(addons);
1

# Parameters

addons
Array<Object>
addon
Object Hide properties
id
String Required
Addon id
quantity
Number
Addon quantity
quantity_in_decimal
String
Addon quantity in decimal

# incrementPlanQuantity

Use this to increment plan quantity by 1.

# Syntax

product.incrementPlanQuantity();
1

# decrementPlanQuantity

Use this to decrement plan quantity by 1.

# Syntax

product.decrementPlanQuantity();
1

# incrementAddonQty

# Syntax

product.incrementAddonQty(addonId);
1

# Parameters

addonId
String
addon id

# decrementAddonQty

# Syntax

product.decrementAddonQty(addonId);
1

# Parameters

addonId
String
addon id

# addCoupon

# Syntax

product.addCoupon(coupon);
1

# Parameters

coupon
String
coupon id

# setCustomData

You can set subscription level custom fields with this method. This information is passed and pre-filled in checkout automatically.

# Syntax

product.setCustomData(subscriptionData);
1

# Example

product.setCustomData({cf_data1: "test", cf_data2: "test2"});
1

# addCharge

# Syntax

product.addCharge(chargeId);
1

# removeCharge

# Syntax

product.removeCharge(chargeId);
1

# incrementChargeQty

Use this to increment charge quantity by 1.

# Syntax

product.incrementChargeQty(chargeId);
1

# decrementChargeQty

Use this to decrement charge quantity by 1.

# Syntax

product.decrementChargeQty(chargeId);
1