# Estimate Functions

Note:
This feature is currently supported only for Product Catalog 1.0.

# 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
chargebee.js script should be loaded through Chargebee server for PCI compliance. DO NOT download and load it via your server.

# ​​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.

Note: Ensure that a publishable API key that has been configured to “Allow Estimate API Calls” is used for invoking Estimates 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

# 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

# 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

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

# 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

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

# 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

# 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