API Version
Product Catalog
Library

Estimates, as the name implies, can be used to find out the estimate for performing an operation as against performing the operation itself. i.e Say you want to create a new subscription or update an existing one, using the estimate API one can deduce the details like how much money the customer needs to be charged for this operation, when it should be collected, the state the subscription would be in etc.

Note:
  • Invoking these APIs do not perform the actual operation but just generates an estimate.
  • Prorated Credits and Promotional Credits are not taken into account while generating the estimate.

Sample estimate [ JSON ]

{ "amount": 895, "amount_due": 895, "collect_now": true, "created_at": 1517506678, "credits_applied": 0, "line_items": [ { "amount": 895, "date_from": 1517506678, "date_to": 1519925878, "description": "No Trial", "entity_id": "no_trial", "entity_type": "plan", "is_taxed": false, "object": "line_item", "quantity": 1, "tax": 0, "type": "charge", "unit_amount": 895 } ], "object": "estimate", "price_type": "tax_exclusive", "recurring": true, "sub_total": 895, "subscription_status": "active", "term_ends_at": 1519925878 }

API Index URL GET

https://{site}.chargebee.com/api/v1/estimates

Model Class

created_at
timestamp(UTC) in seconds
The time at which this estimate got generated
recurring
boolean, default=true
Whether or not the estimate for the invoice is recurring. Will be 'true' or 'false' for subscription related estimates.
subscription_id
optional, string, max chars=100
Applicable only for subsctiption related estimates. The identifier of the subscription this estimate belongs to.
subscription_status
optional, enumerated string
Applicable only for subsctiption related estimates. The post-operation status of the subscription.
Possible values are
futureThe subscription is scheduled to start at a future date.in_trialThe subscription is in trial.activeThe subscription is active and will be charged for automatically based on the items in it.non_renewingThe subscription will be canceled at the end of the current term.
Show all values[+]
term_ends_at
optional, timestamp(UTC) in seconds
Applicable only for subsctiption related estimates. End of the current billing term
collect_now
boolean
'true' means the estimate amount needs to be collected immediately, whereas 'false' means the estimate amount needs to be collected at the term-end
price_type
enumerated string, default=tax_exclusive
The price type of the invoice.
Possible values are
tax_exclusiveAll amounts in the document are exclusive of tax.tax_inclusiveAll amounts in the document are inclusive of tax.
Show all values[+]
amount
in cents, default=0, min=0
Total estimate amount in cents. The 'collect_now' field indicates when this amount needs to be collected.
credits_applied
in cents, default=0, min=0
credits applied to this invoice in cents.
amount_due
in cents, default=0, min=0
Invoice amount due in cents
sub_total
in cents, min=0
The sub-total amount
optional, list of line_item
The list of items in this estimate
optional, list of discount
The list of discounts applied to this estimate
optional, list of tax
The list of taxes applied to this estimate
created_at created_at
timestamp(UTC) in seconds
The time at which this estimate got generated
recurring recurring
boolean, default=true
Whether or not the estimate for the invoice is recurring. Will be 'true' or 'false' for subscription related estimates.
subscription_id subscription_id
optional, string, max chars=100
Applicable only for subsctiption related estimates. The identifier of the subscription this estimate belongs to.
subscription_status subscription_status
optional, enumerated string
Applicable only for subsctiption related estimates. The post-operation status of the subscription.
term_ends_at term_ends_at
optional, timestamp(UTC) in seconds
Applicable only for subsctiption related estimates. End of the current billing term
collect_now collect_now
boolean
'true' means the estimate amount needs to be collected immediately, whereas 'false' means the estimate amount needs to be collected at the term-end
price_type price_type
enumerated string, default=tax_exclusive
The price type of the invoice.
amount amount
in cents, default=0, min=0
Total estimate amount in cents. The 'collect_now' field indicates when this amount needs to be collected.
credits_applied credits_applied
in cents, default=0, min=0
credits applied to this invoice in cents.
amount_due amount_due
in cents, default=0, min=0
Invoice amount due in cents
sub_total sub_total
in cents, min=0
The sub-total amount
line_items
optional, list of line_item
The list of items in this estimate
discounts
optional, list of discount
The list of discounts applied to this estimate
taxes
optional, list of tax
The list of taxes applied to this estimate
Generates an estimate for the 'create subscription' operation. This input will be similar to the Create Subscription API but no subscription will be created, but just an estimate will be generated.

Note:

  • If you use the EU VAT tax option, you need to specify 'billing_address[country]' and 'customer[vat_number]' attributes for the tax calculation to happen. If these attributes are not passed, the tax will be ignored for this estimate.
  • If you use the Customized Tax option, you need to specify the shipping address and billing address parameters for the tax calculation to happen. This is because Chargebee will use the customer’s shipping address to determine the tax applicable. If the shipping address is not available, then the billing address will be used to determine tax. If both addresses are not available, tax will be ignored for this estimate.

Related Tutorial

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/estimates/create_subscription \
     -u {site_api_key}:\
     -d subscription[plan_id]="no_trial" 
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "estimate": {
        "amount": 895,
        "amount_due": 895,
        "collect_now": true,
        "created_at": 1517506678,
        "credits_applied": 0,
        "line_items": [
            {
                "amount": 895,
                "date_from": 1517506678,
                "date_to": 1519925878,
                "description": "No Trial",
                "entity_id": "no_trial",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 895
            },
            {..}
        ],
        "object": "estimate",
        "price_type": "tax_exclusive",
        "recurring": true,
        "sub_total": 895,
        "subscription_status": "active",
        "term_ends_at": 1519925878
    }
}

URL Format POST

https://{site}.chargebee.com/api/v1/estimates/create_subscription

Method

billing_cycles[]
optional, integer, min=0
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
subscription[id]
optional, string, max chars=50
subscription[plan_id]
required, string, max chars=100
subscription[plan_quantity]
optional, integer, default=1, min=1
subscription[trial_end]
optional, timestamp(UTC) in seconds
subscription[start_date]
optional, timestamp(UTC) in seconds
subscription[coupon]
optional, string, max chars=100
billing_address[state_code]
optional, string, max chars=50
billing_address[zip]
optional, string, max chars=20
billing_address[country]
optional, string, max chars=50
shipping_address[state_code]
optional, string, max chars=50
shipping_address[zip]
optional, string, max chars=20
shipping_address[country]
optional, string, max chars=50
customer[vat_number]
optional, string, max chars=20
customer[taxability]
optional, enumerated string, default=taxable
Possible values are
taxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
Show all values[+]
addons[id][0..n]
optional, string, max chars=100
addons[quantity][0..n]
optional, integer, default=1, min=1
estimate estimate
always returned
Resource object representing estimate

Sample admin console URL

https://{site}.chargebee.com/admin-console/estimates/123x
Create a subscription for the existing estimate of a customer.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/customers/__test__5SK2liZoRZxq5Tg18/create_subscription_estimate \
     -u {site_api_key}:\
     --data-urlencode subscription[plan_id]="no_trial"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "estimate": {
        "amount": 895,
        "amount_due": 895,
        "collect_now": true,
        "created_at": 1517480027,
        "credits_applied": 0,
        "line_items": [
            {
                "amount": 895,
                "date_from": 1517480027,
                "date_to": 1519899227,
                "description": "No Trial",
                "entity_id": "no_trial",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 895
            },
            {..}
        ],
        "object": "estimate",
        "price_type": "tax_exclusive",
        "recurring": true,
        "sub_total": 895,
        "subscription_status": "active",
        "term_ends_at": 1519899227
    }
}

URL Format GET

https://{site}.chargebee.com/api/v1/customers/{customer-id}/create_subscription_estimate

Method

use_customer_balances[]
optional, boolean, default=false
If true, all the existing balances - promotional credits, refundable credits and excess payments - will be included for the invoice estimate.
billing_cycles[]
optional, integer, min=0
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
subscription[id]
optional, string, max chars=50
subscription[plan_id]
required, string, max chars=100
subscription[plan_quantity]
optional, integer, default=1, min=1
subscription[trial_end]
optional, timestamp(UTC) in seconds
subscription[start_date]
optional, timestamp(UTC) in seconds
subscription[coupon]
optional, string, max chars=100
shipping_address[state_code]
optional, string, max chars=50
shipping_address[zip]
optional, string, max chars=20
shipping_address[country]
optional, string, max chars=50
addons[id][0..n]
optional, string, max chars=100
addons[quantity][0..n]
optional, integer, default=1, min=1
estimate estimate
always returned
Resource object representing estimate

Sample admin console URL

https://{site}.chargebee.com/admin-console/estimates/123x

Generates an estimate for the 'update subscription' operation. The input will be similar to the Update Subscription API but subscription will not be updated, but just an estimate will be generated.

In case 'update subscription' operation will not create an invoice immediately, the estimate generated will be for the 'end of term' invoice. Some of the cases where the invoice will not be generated immediately are

  • In case of downgrades only credits will be added to customer.
  • 'end_of_term' option is true.
  • 'prorate' option is false.
  • Only coupon is applied.

Note:

  • If you use the EU VAT tax option, you need to specify 'billing_address[country]' and 'customer[vat_number]' attributes for the tax calculation to happen. If these attributes are not passed, the tax will be ignored for this estimate.
  • If you use the Customized Tax option, you need to specify the shipping address and billing address parameters for the tax calculation to happen. This is because Chargebee will use the customer’s shipping address to determine the tax applicable. If the shipping address is not available, then the billing address will be used to determine tax. If both addresses are not available, tax will be ignored for this estimate.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/estimates/update_subscription \
     -u {site_api_key}:\
     -d subscription[id]="__test__5SK0bLNFRFuBxbNB6" \
     -d subscription[plan_id]="plan1" 
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "estimate": {
        "amount": 1500,
        "amount_due": 1500,
        "collect_now": true,
        "created_at": 1517506678,
        "credits_applied": 0,
        "line_items": [
            {
                "amount": 1500,
                "date_from": 1517506678,
                "date_to": 1519925878,
                "description": "Plan1 - Prorated Charges",
                "entity_id": "plan1",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "prorated_charge",
                "unit_amount": 1500
            },
            {..}
        ],
        "object": "estimate",
        "price_type": "tax_exclusive",
        "recurring": true,
        "sub_total": 1500,
        "subscription_id": "__test__5SK0bLNFRFuBxbNB6",
        "subscription_status": "active",
        "term_ends_at": 1519925878
    }
}

URL Format POST

https://{site}.chargebee.com/api/v1/estimates/update_subscription

Method

replace_addon_list[]
optional, boolean, default=false
Should be true if the existing addons should be replaced with the ones that are being passed.
billing_cycles[]
optional, integer, min=0
The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan is used.
prorate[]
optional, boolean
  • When true: Prorated credits or charges are created as applicable for this change.
  • When false: The subscription is changed without creating any credits or charges.
  • When not provided, the value configured in the site settings is considered.
Caveat

For further changes within the same billing term, when prorate is set to true, credits are not created when all the conditions below hold true:

An immediate previous change was made

  • with prorate set to false and
  • no changes were made to the subscription’s billing term and
  • a change was made to either the subscription’s plan, its addons, or the prices of the plan or addons.
end_of_term[]
optional, boolean, default=false
Set this to true if you want the update to be applied at the end of the current subscription billing cycle.
include_delayed_charges[]
optional, boolean, default=false
If true, all the unbilled charges will be included for the invoice estimate.
use_customer_balances[]
optional, boolean, default=false
If true, all the existing balances - promotional credits, refundable credits and excess payments - will be included for the invoice estimate.
subscription[id]
required, string, max chars=50
subscription[plan_id]
optional, string, max chars=100
subscription[plan_quantity]
optional, integer, default=1, min=1
subscription[start_date]
optional, timestamp(UTC) in seconds
subscription[trial_end]
optional, timestamp(UTC) in seconds
subscription[coupon]
optional, string, max chars=100
billing_address[state_code]
optional, string, max chars=50
billing_address[zip]
optional, string, max chars=20
billing_address[country]
optional, string, max chars=50
shipping_address[state_code]
optional, string, max chars=50
shipping_address[zip]
optional, string, max chars=20
shipping_address[country]
optional, string, max chars=50
customer[vat_number]
optional, string, max chars=20
addons[id][0..n]
optional, string, max chars=100
addons[quantity][0..n]
optional, integer, default=1, min=1
addons[proration_type][0..n]
optional, enumerated string
Possible values are
full_termpartial_termnone
Show all values[+]
estimate estimate
always returned
Resource object representing estimate

Sample admin console URL

https://{site}.chargebee.com/admin-console/estimates/123x

This returns an estimate of the amount that will be charged when the subscription renews. The estimate is calculated based on the items present in the subscription. This includes the plan, addons and coupons(if any) of the subscription. This API is not supported for "Cancelled" subscriptions.

You can also specify whether you need the estimate to include delayed charges.

For "Non Renewing" subscriptions, only delayed charges(one time charges and non renewing addons) that may have been added to the subscription to be charged at the end of the current term will be included. Plan, addons and coupons(if any) of the subscription will not be included.

This API will not generate a renewal invoice if an advance invoice is already present for the subscription.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuBxMhAX/renewal_estimate \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "estimate": {
        "amount": 895,
        "amount_due": 895,
        "collect_now": false,
        "created_at": 1517506678,
        "credits_applied": 0,
        "line_items": [
            {
                "amount": 895,
                "date_from": 1519925877,
                "date_to": 1522604277,
                "description": "No Trial",
                "entity_id": "no_trial",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 895
            },
            {..}
        ],
        "object": "estimate",
        "price_type": "tax_exclusive",
        "recurring": true,
        "sub_total": 895,
        "subscription_id": "__test__5SK0bLNFRFuBxMhAX",
        "subscription_status": "active",
        "term_ends_at": 1519925877
    }
}

URL Format GET

https://{site}.chargebee.com/api/v1/subscriptions/{subscription-id}/renewal_estimate

Method

include_delayed_charges[]
optional, boolean, default=true
If true, all the unbilled charges will be included for the invoice estimate.
use_customer_balances[]
optional, boolean, default=false
If true, all the existing balances - promotional credits, refundable credits and excess payments - will be included for the invoice estimate.
estimate estimate
always returned
Resource object representing estimate

Sample admin console URL

https://{site}.chargebee.com/admin-console/estimates/123x

Generates an estimate for the 'create an invoice' operation. This is similar to the Create an invoice API, but the invoice will not be generated. Only an estimate for this operation is created.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/estimates/create_invoice \
     -u {site_api_key}:\
     -d invoice[customer_id]="__test__5SK2liZoRZxq5Dum" 
     -d charges[amount][0]=1000 \
     -d charges[description][0]="Adhoc charge" 
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "estimate": {
        "amount": 1000,
        "amount_due": 1000,
        "collect_now": true,
        "created_at": 1517480026,
        "credits_applied": 0,
        "line_items": [
            {
                "amount": 1000,
                "date_from": 1517480026,
                "date_to": 1517480026,
                "description": "Adhoc charge",
                "entity_type": "adhoc",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 1000
            },
            {..}
        ],
        "object": "estimate",
        "price_type": "tax_exclusive",
        "recurring": false,
        "sub_total": 1000
    }
}

URL Format POST

https://{site}.chargebee.com/api/v1/estimates/create_invoice

Method

coupon[]
optional, string, max chars=100
The 'One Time' coupon to be applied.
invoice[customer_id]
optional, string, max chars=50
invoice[subscription_id]
optional, string, max chars=50
invoice[po_number]
optional, string, max chars=100
customer[vat_number]
optional, string, max chars=20
customer[taxability]
optional, enumerated string, default=taxable
Possible values are
taxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
Show all values[+]
billing_address[state_code]
optional, string, max chars=50
billing_address[zip]
optional, string, max chars=20
billing_address[country]
optional, string, max chars=50
shipping_address[first_name]
optional, string, max chars=150
shipping_address[last_name]
optional, string, max chars=150
shipping_address[email]
optional, string, max chars=70
shipping_address[company]
optional, string, max chars=250
shipping_address[phone]
optional, string, max chars=50
shipping_address[line1]
optional, string, max chars=150
shipping_address[line2]
optional, string, max chars=150
shipping_address[line3]
optional, string, max chars=150
shipping_address[city]
optional, string, max chars=50
shipping_address[state_code]
optional, string, max chars=50
shipping_address[state]
optional, string, max chars=50
shipping_address[zip]
optional, string, max chars=20
shipping_address[country]
optional, string, max chars=50
addons[id][0..n]
optional, string, max chars=100
addons[quantity][0..n]
optional, integer, default=1, min=1
charges[amount][0..n]
optional, in cents, min=1
charges[description][0..n]
optional, string, max chars=250
estimate estimate
always returned
Resource object representing estimate

Sample admin console URL

https://{site}.chargebee.com/admin-console/estimates/123x