# 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)
1

# 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.
publishableKey
Boolean
This will be used for Chargebee.js functions (VAT validation, estimate APIs) and components & fields tokenization. See more info on, how to use a publishable key here.
iframeOnly
Boolean
This wil work only on mobile browsers. Set true to open the Checkout or Portal as an iFrame on the same browser tab.

When this is set to true,
  • If Checkout or Portal is opened from within an application, it opens in a WebView tab.
  • If Checkout or Portal is opened from a WebView tab, it opens on the same WebView tab.
  • If Checkout or Portal is opened from a browser tab, it opens on the same browser tab.
enableGATracking
Boolean
This will enable Google Analytics (analytics.js) tracking. Follow the steps to integrate Google Analytics with Chargebee checkout(In-app checkout).
enableFBQTracking
Boolean
This will enable Facebook pixel tracking. Follow the steps to integrate Facebook pixel tracking with Chargebee checkout (In-app checkout).
enableRefersionTracking
Boolean
This will enable Refersion tracking (Referral integration). Learn more about Chargebee-Refersion integration .

Note: This is available only in PC 1.0

enableGTMTracking
Boolean
This will enable Google tag manager). Learn more about on how to use Google Analytics via GTM in Chargebee.
isItemsModel
Boolean
This will enable support for product catalog 2.0
businessEntityId
String
The unique ID of the business entity under whose context the cart object or the drop-in script should work.
If not provided, the default business entity defined for the site is considered.
Note:
  • This parameter is applicable only when multiple business entities have been created for the site.
  • Multiple Business Entities is currently in early access. Contact [email protected] to join the Early Adopter Program and enable this feature.

# 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
})
1
2
3
4
5

# getInstance

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

# Syntax

Chargebee.getInstance();
1

# 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();
1

# 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"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 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)
1

# Parameters

options
Object Required Hide properties
hostedPage
Function Required
This function should return a promise that resolves a hosted page object
layout
Enum
Specifies the checkout layout that overrides the default checkout layout configured in the Checkout & Self-Serve Portal settings.

Early Access
The layout parameter is currently in early access. Contact [email protected] to join the Early Adopter Program.

Allowed Values: in_app
full_page
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
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 - Hide
currentStep
String

# 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
  }
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# createChargebeePortal

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

# Syntax

chargebeeInstance.createChargebeePortal()
1

# Return value

chargebee portal instance object

# Example

var chargebeePortalInstance = chargebeeInstance.createChargebeePortal()
1

# 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)
1

# 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);
  });
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 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()
1

# closeAll

This function is used to close all Chargebee modals.

# Syntax

chargebeeInstance.closeAll()
1

# 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)
1

# 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 - 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 in 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
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
subscriptionCancelled
Function
This function will be called when a subscription is cancelled
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
subscriptionResumed
Function
This function will be called when a subscription is resumed
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
subscriptionPaused
Function
This function will be called when a subscription is paused
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
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
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
subscriptionReactivated
Function
This function will be called when a cancelled subscription is reactivated
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
forwardOptions
Object Hide properties
sectionType
String Required
Allowed Values: All values present in Chargebee.getPortalSections()
params
Object Hide properties
subscriptionId
String Required if the sectionType involves a subscription related action
paymentSourceId
String Required if the sectionType involves a payment source related action

# 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
  },
   scheduledCancellationRemoved: function(data) {
    // Optional
    // called when the schedule to cancel 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
  }
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

# 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"
    }
  }
);
1
2
3
4
5
6
7
8
9
10
11

# 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)
1

# Parameters

options
Object Hide properties
sectionType
String
params
Object Hide properties
subscriptionId
String Required if the sectionType involves a subscription
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 in 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
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
subscriptionCancelled
Function
This function will be called when a subscription is cancelled
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
subscriptionResumed
Function
This function will be called when a subscription is resumed
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
subscriptionPaused
Function
This function will be called when a subscription is paused
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String
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
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
subscriptionReactivated
Function
This function will be called when a cancelled subscription is reactivated
Arguments - Hide
data
Object Hide properties
subscription
Object Hide properties
id
String

# Example

var cbInstance = Chargebee.getInstance();
var cbPortal = cbInstance.createChargebeePortal();
cbPortal.openSection({
  sectionType: Chargebee.getPortalSections().ACCOUNT_DETAILS
}
1
2
3
4
5

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.