Chargebee JS API reference

This reference is for API based integration. If you are integrating using Drop-in script use this reference instead.

Chargebee object

init

This function is used to create chargebee instance object to open checkout and portal.

Syntax

Chargebee.init(options)

Parameters

options
Object Required Hide properties
site
String Required
Your site name
domain
String Required if custom domain is enabled
Your custom domain
Eg: https://billing.yourdomain.com
enableFriendbuyTracking
Boolean
If this is enabled, Chargebee will send customer information and order information to friendbuy and will also open friendbuy's post purchase widget based on your integration settings. Please make sure you whitelist your domain in the checkout settings page.
enableRedirectMode
Boolean
If this is enabled, end user will be redirected to chargebee checkout and self-serve portal page instead of opening in a modal box. This is needed, if amazon pay is configured as one of your supported payment methods. Please make sure you have configured redirect URL in checkout and self-serve portal, so that the user is able to navigate back to the app.

Return value

chargebee instance object

Example

var chargebeeInstance = Chargebee.init({
  site: "site-name", // your test site
  domain: "https://mybilling.acme.com" // this is an optional parameter.
  // Use this, if custom domain is enabled for your site
})

getInstance

This function will return 'chargebee instance' object created using init() function.

Syntax

Chargebee.getInstance();

Return value

chargebee instance object

Error will be thrown if instance is not created.

getPortalSections

This function will return an object with all the available sections in Chargebee customer portal. This section name can be used to forward an user to a particular section or just to open the section as an individual card.

Syntax

Chargebee.getPortalSections();

Output

{
  "SUBSCRIPTION_DETAILS": "sub_details",
  "SUBSCRIPTION_CANCELLATION": "sub_cancel",
  "EDIT_SUBSCRIPTION": "edit_subscription",
  "VIEW_SCHEDULED_CHANGES": "scheduled_changes",
  "ACCOUNT_DETAILS": "account_details",
  "EDIT_ACCOUNT_DETAILS": "portal_edit_account",
  "ADDRESS": "portal_address",
  "EDIT_BILLING_ADDRESS": "portal_edit_billing_address",
  "EDIT_SHIPPING_ADDRESS": "portal_edit_shipping_address",
  "EDIT_SUBSCRIPTION_CUSTOM_FIELDS": "portal_edit_subscription_cf",
  "PAYMENT_SOURCES": "portal_payment_methods",
  "ADD_PAYMENT_SOURCE": "portal_add_payment_method",
  "EDIT_PAYMENT_SOURCE": "portal_edit_payment_method",
  "VIEW_PAYMENT_SOURCE": "portal_view_payment_method",
  "CHOOSE_PAYMENT_METHOD_FOR_SUBSCRIPTION": "portal_choose_payment_method",
  "BILLING_HISTORY": "portal_billing_history"
}

Chargebee instance object

Chargebee instance object is used to open checkout and to create chargebee portal instance object.

openCheckout

This function is used to open checkout page.

Syntax

chargebeeInstance.openCheckout(options)

Parameters

options
Object Required Hide properties
hostedPage
Function Required
This function should return a promise that resolves a hosted page object
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 - View
close
Function
This function will be called once the checkout is closed by the end user
step
Function
This function will be called everytime an 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 - View

Example

chargebeeInstance.openCheckout({
  hostedPage: function() {
    // required
    // This function should return a promise, that will resolve a hosted page object
    // If the library that you use for making ajax calls, can return a promise,
    // you can directly return that.
    return new Promise(function(resolve, reject){
      // This sampe response should be fetched as a result of an ajax call
      var sampleResponse = {
        "id": "8ajOxcuyG692GDy9yjnZ2hNM1ATugOFQl",
        "type": "checkout_new",
        "url": "https://yourapp.chargebee.com/pages/v3/8ajOxcuyG692GDy9yjnZ2hNM1ATugOFQl/",
        "state": "created",
        "embed": true,
        "created_at": 1515494821,
        "expires_at": 1515498421
      }
      resolve(sampleResponse);
    });
  },
  loaded: function() {
    // Optional
    // will be called once checkout page is loaded
  },
  error: function(error) {
    // Optional
    // will be called if the promise passed causes an error
  },
  step: function(step) {
    // Optional
    // will be called for each step involved in the checkout process
  },
  success: function(hostedPageId) {
    // Optional
    // will be called when a successful checkout happens.
  },
  close: function() {
    // Optional
    // will be called when the user closes the checkout modal box
  }
})

createChargebeePortal

This function will create a chargebee portal instance which opens Chargebee’s self-serve portal.

Syntax

chargebeeInstance.createChargebeePortal()

Return value

chargebee portal instance object

Example

var chargebeePortalInstance = chargebeeInstance.createChargebeePortal()

setPortalSession

This function is used to open customer portal with single-sign-on(SSO) enabled.

Enable SSO(single-sign-on) in Chargebee portal settings page.

Syntax

chargebeeInstance.setPortalSession(setterFunction)

Parameters

setterFunction
Function
This function should return a promise that resolves a portal session object

Example

chargebeeInstance.setPortalSession(function() {
// This function should return a promise, that will resolve a portal session object
// If the library that you use for making ajax calls, can return a promise, you can directly return that.
  return new Promise(function(resolve, reject){
    // This sampe response should be fetched as a result of an ajax call
    var sampleResponse = {
      "id": "portal_XpbGElGQgEHspHB",
      "token": "cuqdrWacuITd2cabvf97KJD73SpNcd7BICB",
      "access_url": "https://yourapp.chargebeeportal.com/portal/access/cuqdrWacuITd2cabvf97KJD73SpNcd7BICB",
      "status": "created",
      "created_at": 1515494835,
      "expires_at": 1515498435,
      "object": "portal_session",
      "customer_id": "XpbGEt7QgEHsnL7O"
    }
    resolve(sampleResponse);
  });
})

logout

This function is used to logout Chargebee’s session. If you do not call this function, the session will be valid for a maximum of one hour.

Syntax

chargebeeInstance.logout()

closeAll

This function is used to close all Chargebee modals.

Syntax

chargebeeInstance.closeAll()

Chargebee portal instance object

Chargebee portal instance object is used to do portal related actions.

open

This function is used to open Chargebee’s self-serve portal.

Syntax

chargebeePortalInstance.open(options, forwardOptions)

Parameters

options
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 - View
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 in portal
subscriptionChanged
Function
This function will be called whenever a subscription is changed
Arguments - View
subscriptionCustomFieldsChanged
Function
This function will be called whenever a subscription custom fields are changed
Arguments - View
subscriptionCancelled
Function
This function will be called when a subscription is cancelled
Arguments - View
subscriptionResumed
Function
This function will be called when a subscription is resumed
Arguments - View
subscriptionPaused
Function
This function will be called when a subscription is paused
Arguments - View
scheduledPauseRemoved
Function
This function will be called when a subscription that is scheduled for pause is removed
Arguments - View
subscriptionReactivated
Function
This function will be called when a cancelled subscription is reactivated
Arguments - View
forwardOptions
Object Hide properties
sectionType
String Required
Allowed Values: All values present in Chargebee.getPortalSections()
params
Object View properties

Example

chargebeePortalInstance.open({
  loaded: function() {
    // Optional
    // called when chargebee portal is loaded
  },
  close: function() {
    // Optional
    // called when chargebee portal is closed
  },
  visit: function(sectionName) {
    // Optional
    // called whenever the customer navigates across different sections in portal
  },
  paymentSourceAdd: function() {
    // Optional
    // called whenever a new payment source is added in portal
  },
  paymentSourceUpdate: function() {
    // Optional
    // called whenever a payment source is updated in portal
  },
  paymentSourceRemove: function() {
    // Optional
    // called whenever a payment source is removed in portal.
  },
  subscriptionChanged: function(data) {
    // Optional
    // called whenever a subscription is changed
    // data.subscription.id will give you the subscription id
    // Make sure you whitelist your domain in the checkout settings page
  },
  subscriptionCustomFieldsChanged: function(data) {
    // Optional
    // called whenever a subscription custom fields are changed
    // data.subscription.id will give you the subscription id
    // Make sure you whitelist your domain in the checkout settings page
  },
  subscriptionCancelled: function(data) {
    // Optional
    // called when a subscription is cancelled
    // data.subscription.id will give you the subscription id
    // Make sure you whitelist your domain in the checkout settings page
  },
  subscriptionPaused: function(data) {
    // Optional
    // called when a subscription is Paused.
    // data.subscription.id will give you the subscription id
    // Make sure you whitelist your domain in the checkout settings page
  },
  subscriptionResumed: function(data) {
    // Optional
    // called when a paused subscription is resumed.
    // data.subscription.id will give you the subscription id
    // Make sure you whitelist your domain in the checkout settings page
  },
  scheduledPauseRemoved: function(data) {
    // Optional
    // called when the schedule to pause a subscription is removed for that subscription.
    // data.subscription.id will give you the subscription id
    // Make sure you whitelist your domain in the checkout settings page
  },
  subscriptionReactivated: function(data) {
    // Optional
    // called when a cancelled subscription is reactivated.
    // data.subscription.id will give you the subscription id
    // Make sure you whitelist your domain in the checkout settings page
  }
})

Example for forwarding the user to a specific section after opening customer portal

To redirect the user to a specific section while opening customer portal, the section name along with the supported params need to be passed.

var cbInstance = Chargebee.getInstance();
var cbPortal = cbInstance.createChargebeePortal();
var callbacks = {};
cbPortal.open(callbacks,
  {
    sectionType: Chargebee.getPortalSections().EDIT_SUBSCRIPTION,
    params: {
      subscriptionId: "active_direct"
    }
  }
);

openSection

Use this method if you want to open a particular section as a separate card, instead of opening the entire customer portal.

Only the below section types can be opened as a separate card

  • SUBSCRIPTION_DETAILS
  • ACCOUNT_DETAILS
  • ADDRESS
  • PAYMENT_SOURCES
  • BILLING_HISTORY

Syntax

cbPortal.openSection(options, callbacks)

Parameters

options
Object Hide properties
sectionType
String
params
Object View properties
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 - View
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 in portal
subscriptionChanged
Function
This function will be called whenever a subscription is changed
Arguments - View
subscriptionCustomFieldsChanged
Function
This function will be called whenever a subscription custom fields are changed
Arguments - View
subscriptionCancelled
Function
This function will be called when a subscription is cancelled
Arguments - View
subscriptionResumed
Function
This function will be called when a subscription is resumed
Arguments - View
subscriptionPaused
Function
This function will be called when a subscription is paused
Arguments - View
scheduledPauseRemoved
Function
This function will be called when a subscription that is scheduled for pause is removed
Arguments - View
subscriptionReactivated
Function
This function will be called when a cancelled subscription is reactivated
Arguments - View

Example

var cbInstance = Chargebee.getInstance();
var cbPortal = cbInstance.createChargebeePortal();
cbPortal.openSection({
  sectionType: Chargebee.getPortalSections().ACCOUNT_DETAILS
}

All the callbacks that are supported in the portal will be supported when a section of the portal is opened as a separete section using this method.