# Estimate Functions
# Introduction
"Estimates", as the name implies, can be used to find out the estimate for performing an operation as against performing the operation itself. Say, 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.
# Integration
# Inserting Chargebee.js script in your application
Include the following script in your HTML page. You need to do this only once per page
<script src="https://js.chargebee.com/v2/chargebee.js"></script>
1
# Initializing the Chargebee Instance
Inside your JavaScript code, initialize Chargebee once the page is loaded and initialize the Chargebee object. This object is used to invoke the various functions.
let cbInstance = Chargebee.init({
site: "mannar-test",
publishableKey: 'test_Zxm7GgZmjdHO3tT8icuGaYkYBvH0QNRr4'
});
// You can access the above created instance anywhere using the following code
let cbInstance = Chargebee.getInstance();
1
2
3
4
5
6
7
2
3
4
5
6
7
# Initialize Chargebee.js functions
Use the load method to load and initialize the functions module. Then, for instance, use the estimates.createSubscriptionEstimate to invoke the create subscription estimate function.
let cbInstance = Chargebee.getInstance();
cbInstance.load('functions').then(() => {
// your code here
});
1
2
3
4
2
3
4
# List of available estimate functions
# Create Subscription Estimate
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.
# Sample Response
{"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
# Update Subscription Estimate
Generates an estimate for the 'update subscription' operation. The input will be similar to the Update Subscription (opens new window) API but subscription will not be updated, only an estimate will be 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.
# Sample Response
{"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
# Subscription Renewal Estimate
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.
# Sample Response
{"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
