# Chargebee Instance Object
Use chargebee instance object for enabling payment integrations, analytics like Google Analytics and Facebook pixel tracking, checkout and portal integrations, and more.
To ensure that you receive all the callbacks which you set, do whitelist your domain in Chargebee. You can whitelist your domain here, Settings > Configure Chargebee >Checkout & Self-Serve Portal Settings > Configuration > Advanced Settings > Add domains
These are the functionalities:
- Checkout and Portal Integration (Drop-in and API)
- Components and Fields
- Payment Integrations
- Functions
# Checkout and Portal Integration
Use the functions below to use and modify Checkout and Portal integrations on your website.
# setBusinessEntity
Sets the business entity context for checkout.
# Syntax
cbInstance.setBusinessEntity(businessEntityId)
1
# Parameters
entityId
String Required Id of business entity.
# Return value
This function returns a promise.
# Example
const cbInstance = Chargebee.init({
site: "moments-test",
isItemsModel: true, // Product catalog 2.0
});
cbInstance.setBusinessEntity("acme-inc-us");
const cart = cbInstance.getCart();
const product = cbInstance.initializeProduct("silver-USD-monthly");
cart.replaceProduct(product);
cart.proceedToCheckout();
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# openCheckout
This function is used to open checkout page.
# Syntax
cbInstance.openCheckout(options)
1
# Parameters
options
Object Required Hide properties# Return value
NA
# Example
cbInstance.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
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
TIP
Find the entire suppported callbacks for Checkout.
# getCart
This function retrieves the cart object.
# Syntax
const cart = cbInstance.getCart();
1
# Return value
# Example
const cbInstance = Chargebee.init({
site: "moments-test",
isItemsModel: true, // Product catalog 2.0
});
cbInstance.setBusinessEntity("acme-inc-us");
const cart = cbInstance.getCart();
const product = cbInstance.initializeProduct("silver-USD-monthly");
cart.replaceProduct(product);
cart.proceedToCheckout();
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# getProduct
This function retrieves the Product object associated with a checkout button.
# Syntax
cbInstance.getProduct(checkoutButtonElement)
1
# Parameters
checkoutButtonElement
Required HTML Element associated with the checkout button.
# Return value
# Example
<a href="javascript:void(0)" id="diamond-subscribe-button" data-cb-type="checkout" data-cb-item-0="diamond-USD-monthly" data-cb-item-1="silver-pass-USD-monthly" data-cb-item-1-quantity="2" >
Subscribe
</a>
1
2
3
2
3
const subscribeButton = document.getElementById("diamond-subscribe-button");
// Get product object from HTML element
const product = cbInstance.getProduct(subscribeButton);
1
2
3
2
3
# initializeProduct
This function initializes the Product object.
# Syntax
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
A function that resolves into a product object.
# Example
const product = cbInstance.initializeProduct("diamond-USD-monthly", 2);
1
# setCheckoutCallbacks
You can use this function to set callbacks with respect to checkout.
# Syntax
cbInstance.setCheckoutCallbacks(setterFunction);
1
# Parameters
setterFunction
Function # Return value
NA
# Example
cbInstance.setCheckoutCallbacks(cart => {
return {
success: (hostedPageId) => {
console.log('Successful checkout', hostedPageId)
},
error: (err) => {
console.error(err);
}
}
})
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
# createChargebeePortal
This function creates a chargebee portal instance which opens Chargebee’s self-serve portal.
# Syntax
cbInstance.createChargebeePortal()
1
# Return value
# Example
const cbInstance = Chargebee.getInstance();
// Set portal session from browser
cbInstance.setPortalSession(() => portalSession);
// Create chargebee portal
const cbPortal = cbInstance.createChargebeePortal()
// Open portal
cbPortal.open();
1
2
3
4
5
6
7
2
3
4
5
6
7
# setPortalSession
This function is used to open customer portal with the portal session created using Create Portal sessions API (opens new window).
TIP
Enable SSO(single-sign-on) in Chargebee portal settings page.
# Syntax
cbInstance.setPortalSession(setterFunction)
1
# Parameters
setterFunction
Function This function should return a promise that resolves a portal session object.
# Return value
This function returns a promise, that resolves a portal session object.
# Example
cbInstance.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
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 Self serve portal session. When you do not use this function, the current session will be valid for up to an hour only.
# Syntax
cbInstance.logout()
1
# closeAll
This function is used to close all Chargebee modals.
# Syntax
cbInstance.closeAll()
1
# setPortalCallbacks
You can use this function to set callbacks with respect to Self-serve portal.
# Syntax
cbInstance.setPortalCallbacks(callbacks);
1
# Parameters
callbacks
Object Hide properties# Example
cbInstance.setPortalCallbacks({
loaded: () => {
console.log('Portal loaded successfully');
},
subscriptionChanged: (data) => {
console.log('Subscription changed', data.subscription.id)
}
})
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
# Payment Integrations
Use the below functions to use payment integrations on your website.
# load
This function is used to load the given module.
# Syntax
cbInstance.load(moduleName)
1
# Parameters
moduleName
String Required Name of the module to load.
Allowed Values:
components
3ds-handler
functions
ideal
sofort
google-pay
bancontact
giropay
dotpay
paypal
netbanking_emandates
apple-pay
upi
components
3ds-handler
functions
ideal
sofort
google-pay
bancontact
giropay
dotpay
paypal
netbanking_emandates
apple-pay
upi
# Return Value
Returns a promise thats initializes and resolves to the corresponding module handler.
# Example
cbInstance.load('components').then(() => {
// components can be mounted
});
1
2
3
2
3
# load3DSHandler
Use the load3DSHandler method to load and initialize the 3DS Helper module. Then use the threeDSHandler to initiate 3DS flow.
This function loads the 3ds-helper module and initializes 3DS handler object.
# Syntax
cbInstance.load3DSHandler()
1
# Return value
Promise that resolves 3DS handler object.
# Example
cbInstance.load3DSHandler().then((threeDSHandler) => {
// your code here
});
1
2
3
2
3
# create3DSHandler
You can create a 3DS handler object using this method as well. 3ds-handler module should be loaded prior to using this method.
# Syntax
cbInstance.create3DSHandler();
1
# Return value
# Example
cbInstance.load('3ds-handler').then(() => {
let threeDSHandler = cbInstance.create3DSHandler();
// Your code here
})
1
2
3
4
2
3
4
# handlePayment
Use this method to initiate the payment process.
# Syntax
cbInstance.handlePayment(paymentMethodType, paymentOptions);
1
# Parameters
paymentMethodType
Enum Required Name of the payment method type.
Allowed Values:
ideal
sofort
bancontact
giropay
dotpay
netbanking_emandates
direct_debit
ideal
sofort
bancontact
giropay
dotpay
netbanking_emandates
direct_debit
paymentOptions
Object View properties Options for the payment method type.
# Return value
Returns a promise that resolves to an authorized payment intent object
# Example
cbInstance.handlePayment('ideal', {
paymentIntent: () => {
// Make ajax call to your server to create a payment intent
return createPaymentIntent()
}
}).then(paymentIntent => {
// Use the authorized payment intent to create a subscription.
}).catch(err => {
// Payment authorization failed
})
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
# Functions
Chargebee JS supports the below functions:
- Estimates
createSubscriptionEstimateupdateSubscriptionEstimaterenewSubscriptionEstimate
- EU vat validation function
validateVat
# Estimate functions
"Estimates", as the name implies, can be used to find the estimate for performing an operation as against performing the operation itself. For example, if you want to create a new subscription or update an existing one, you can deduce the details such as the amount the customer needs to be charged for this operation, the state the subscription would be in, etc. using the estimate functions.
# createSubscriptionEstimate
Generates an estimate for the 'create subscription' operation. This is similar to the Create Subscription (opens new window) API but no subscription will be created, only an estimate for this operation is created.
# Syntax
let cbInstance = Chargebee.getInstance();
cbInstance.load('functions').then(() => {
const payload = {...}
cbInstance.estimates.createSubscriptionEstimate(payload).then(data => {
// Your code here
}).catch(err => {
// Your code here
})
});
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# Parameters
billing_cycles
Number Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled
terms_to_charge
Number The number of future renewals for which advance invoicing is done. However, if a new term gets started in this operation, the specified terms_to_charge will be inclusive of this new term.
billing_alignment_mode
String Applicable when calendar billing is enabled and subscription is getting created in active / non_renewing states. Unless specified the configured default value will be used.
Allowed Values:
immediate
delayed
immediate
delayed
mandatory_addons_to_remove
Array List of addons IDs that are mandatory to the plan and has to be removed from the subscription
coupon_ids
Array Identifier of the coupon as a List. Coupon Codes can also be passed
invoice_immediately
Boolean Applicable when charges are added during this operation. If specified as false, these charges will be added to unbilled charges. The default value for this parameter will be as per your site settings
client_profile_id
String Indicates the Client profile id for the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
subscription
Object View properties Subscription details
billing_address
Object View properties Parameters for Billing Address
shipping_address
Object View properties Parameters for Shipping Address
customer
Object View properties Parameters for customer
addons
Array<Object> Parameters for addons. Multiple addon objects can be passed in the array
Object View properties
event_based_addons
Array<Object> Parameters for event_based_addons. Multiple event_based_addon objects can be passed in the array
Object View properties
# Return value
Resource object (opens new window) representing estimate.
# Example
{"estimate": {
"created_at": 1517507462,
"invoice_estimate": {
"amount_due": 895,
"amount_paid": 0,
"credits_applied": 0,
"currency_code": "USD",
"date": 1517507462,
"line_item_discounts": [],
"line_item_taxes": [],
"line_items": [
{
"amount": 895,
"date_from": 1517507462,
"date_to": 1519926662,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__5SK0bLNFRFuFFZLf3",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"tax_amount": 0,
"unit_amount": 895
},
{..}
],
"object": "invoice_estimate",
"price_type": "tax_exclusive",
"recurring": true,
"round_off_amount": 0,
"sub_total": 895,
"taxes": [],
"total": 895
},
"object": "estimate",
"subscription_estimate": {
"currency_code": "USD",
"next_billing_at": 1519926662,
"object": "subscription_estimate",
"status": "active"
}
}}
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
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
# `updateSubscriptionEstimate
Generates an estimate for the 'update subscription' operation. While the input is similar to the Update Subscription (opens new window) API, the subscription is not updated and only an estimate is created.
# Syntax***
let cbInstance = Chargebee.getInstance();
cbInstance.load('functions').then(() => {
const payload = {...}
cbInstance.estimates.updateSubscriptionEstimate(payload).then(data => {
// Your code here
}).catch(err => {
// Your code here
})
});
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# Parameters
billing_cycles
Number Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled
terms_to_charge
Number The number of future renewals for which advance invoicing is done. However, if a new term gets started in this operation, the specified terms_to_charge will be inclusive of this new term.
billing_alignment_mode
String Applicable when calendar billing is enabled and subscription is getting created in active / non_renewing states. Unless specified the configured default value will be used.
Allowed Values:
immediate
delayed
immediate
delayed
mandatory_addons_to_remove
Array List of addons IDs that are mandatory to the plan and has to be removed from the subscription
coupon_ids
Array Identifier of the coupon as a List. Coupon Codes can also be passed
invoice_immediately
Boolean Applicable when charges are added during this operation. If specified as false, these charges will be added to unbilled charges. The default value for this parameter will be as per your site settings
subscription
Object View properties Subscription details
billing_address
Object View properties Parameters for Billing Address
shipping_address
Object View properties Parameters for Shipping Address
customer
Object View properties Parameters for customer
addons
Array<Object> Parameters for addons. Multiple addon objects can be passed in the array
Object View properties
event_based_addons
Array<Object> Parameters for event_based_addons. Multiple event_based_addon objects can be passed in the array
Object View properties
replace_addon_list
Boolean Should be true if the existing addons should be replaced with the ones that are being passed
reactivate_from
UTC timestamp The time from which this subscription should be reactivated.
replace_coupon_list
Boolean Should be true if the existing coupons should be replaced with the ones that are being passed.
prorate
Boolean Add Prorated Credits and Charges, if applicable, while updating the subscription. If this parameter is not passed, the default value set in the site settings will be used. Else, it will be assumed as true.
end_of_term
Boolean You can specify when you want to update the subscription.
force_term_reset
Boolean Applicable for 'Active' & 'Non Renewing' states alone. Generally, subscription's term will be reset (i.e current term is ended and a new term starts immediately) when a new plan having different billing frequency is specified in the input. For all other cases, the subscription's term will remain intact. Now for this later scenario, if you want to force a term reset you can specify this param as 'true'. Note: Specifying this value as 'false' has no impact on the default behavior.
reactivate
Boolean Applicable only for canceled subscriptions. Once this is passed as true, canceled subscription will become active; otherwise subscription changes will be made but the the subscription state will remain canceled. If not passed, subscription will be activated only if there is any change in subscription data.
include_delayed_charges
Boolean If true, all unbilled charges will be included for the invoice estimate.
use_existing_balances
Boolean If true, all existing balances - promotional credits, refundable credits and excess payments - will be included for the invoice estimate.
# Return value
Resource object (opens new window) representing estimate.
# Example
{"estimate": {
"created_at": 1517507463,
"credit_note_estimates": [
{
"amount_allocated": 895,
"amount_available": 0,
"currency_code": "USD",
"line_item_discounts": [],
"line_item_taxes": [],
"line_items": [
{
"amount": 895,
"date_from": 1517507463,
"date_to": 1519926663,
"description": "No Trial - Prorated Credits for 01-Feb-2018 - 01-Mar-2018",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__5SK0bLNFRFuFFhhfS",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__5SK0bLNFRFuFFekfI",
"tax_amount": 0,
"unit_amount": 895
},
{..}
],
"object": "credit_note_estimate",
"price_type": "tax_exclusive",
"reference_invoice_id": "__demo_inv__6",
"round_off_amount": 0,
"sub_total": 895,
"taxes": [],
"total": 895,
"type": "adjustment"
},
{..}
],
"invoice_estimate": {
"amount_due": 1500,
"amount_paid": 0,
"credits_applied": 0,
"currency_code": "USD",
"date": 1517507463,
"line_item_discounts": [],
"line_item_taxes": [],
"line_items": [
{
"amount": 1500,
"date_from": 1517507463,
"date_to": 1519926663,
"description": "Plan1 - Prorated Charges",
"discount_amount": 0,
"entity_id": "plan1",
"entity_type": "plan",
"id": "li___test__5SK0bLNFRFuFFhbfQ",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__5SK0bLNFRFuFFekfI",
"tax_amount": 0,
"unit_amount": 1500
},
{..}
],
"object": "invoice_estimate",
"price_type": "tax_exclusive",
"recurring": true,
"round_off_amount": 0,
"sub_total": 1500,
"taxes": [],
"total": 1500
},
"object": "estimate",
"subscription_estimate": {
"currency_code": "USD",
"id": "__test__5SK0bLNFRFuFFekfI",
"next_billing_at": 1519926663,
"object": "subscription_estimate",
"status": "active"
}
}}
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
76
77
78
79
80
81
82
83
84
85
86
87
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
76
77
78
79
80
81
82
83
84
85
86
87
# renewSubscriptionEstimate
This returns an estimate of the amount that will be charged when the subscription is billed next. The estimate is calculated based on the current recurring items of the subscription - plan, addons, and coupons.
# Syntax
let cbInstance = Chargebee.getInstance();
cbInstance.load('functions').then(() => {
const payload = {...}
cbInstance.estimates.renewSubscriptionEstimate(payload).then(data => {
// Your code here
}).catch(err => {
// Your code here
})
});
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# Parameters
subscription
Object View properties Subscription details.
include_delayed_charges
Boolean If true, all unbilled charges will be included for the invoice estimate.
use_existing_balances
Boolean If true, all existing balances - promotional credits, refundable credits and excess payments - will be included for the invoice estimate.
ignore_scheduled_cancellation
Boolean if true, ignores scheduled cancellation for non renewing subscription
ignore_scheduled_changes
Boolean If true, ignores all recurring charges scheduled during renewal
# Return Value
Resource object (opens new window) representing estimate.
# Example
{"estimate": {
"created_at": 1517507462,
"invoice_estimate": {
"amount_due": 895,
"amount_paid": 0,
"credits_applied": 0,
"currency_code": "USD",
"line_item_discounts": [],
"line_item_taxes": [],
"line_items": [
{
"amount": 895,
"date_from": 1519926661,
"date_to": 1522605061,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__5SK0bLNFRFuFFNnek",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__5SK0bLNFRFuFFLAed",
"tax_amount": 0,
"unit_amount": 895
},
{..}
],
"object": "invoice_estimate",
"price_type": "tax_exclusive",
"recurring": true,
"round_off_amount": 0,
"sub_total": 895,
"taxes": [],
"total": 895
},
"object": "estimate",
"subscription_estimate": {
"currency_code": "USD",
"id": "__test__5SK0bLNFRFuFFLAed",
"next_billing_at": 1519926661,
"object": "subscription_estimate",
"status": "active"
}
}}
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
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
# EU vat validation function
Chargebee validates a VAT number by sending a validation request to VAT Information Exchange System (VIES (opens new window)), a search engine owned by the European Commision.
# validateVat
# Syntax
cbInstance.vat.validateVat(payload)
1
# Parameters
country
String 2-letter ISO 3166 alpha-2 country code
vat_number
String EU VAT Number
# Return value
Returns an object with VAT validation status and an optional message.
# Example
{
"status": "INVALID",
"message": "Customer VAT number is invalid"
}
1
2
3
4
2
3
4
# Response Properties
status:
| Validation Status | Description |
|---|---|
| VALID | VAT Number validation was successful and the number is valid |
| INVALID | VAT Number validation failed. |
| UNDETERMINED | No response from VIES, or other errors. |
message: Describes the response received from VIES.
