You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).
    Library
You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).

Estimates

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 }

Estimate attributes

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.cancelledThe subscription has been canceled and is no longer in service.
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.
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
line_items
Show attributes[+]
optional, list of line_item
The list of items in this estimate
Line item attributes
date_from
timestamp(UTC) in seconds
Start date of this line item.
date_to
timestamp(UTC) in seconds
End date of this line item.
unit_amount
in cents
Unit amount of the line item.
quantity
optional, integer, default=1
Quantity of the recurring item which is represented by this line item.
amount
optional, in cents
Total amount of this line item. Typically equals to unit amount x quantity
is_taxed
boolean, default=false
Specifies whether this line item is taxed or not
tax
optional, in cents, default=0, min=0
The tax amount charged for this item
tax_rate
optional, double, min=0.0, max=100.0
Rate of tax used to calculate tax for this lineitem
reference_line_item_id
optional, string, max chars=40
Invoice Reference Line Item ID
description
string, max chars=250
Detailed description about this line item.
type
enumerated string
Type of this lineitem. This along with 'entity_type' and 'entity_id' attributes consitutes the meta information of this lineitem.
Possible values are
chargeRepresents the 'charge' lineitems in invoice. The 'entity_type' attribute further identifies the modelled entity (plan / addon etc) this charge is based onprorated_chargeRepresents the 'charge' lineitems that are pro-rated. The 'entity_type' attribute further identifies the modelled entity (plan / addon etc) this 'prorated charge' is based onsetup_chargeRepresents the 'setup charge' lineitem in invoice - which is a one-time charge included only in the first invoice of the subscription
entity_type
enumerated string
Specifies the modelled entity this line item is based on.
Possible values are
planIndicates that this lineitem is based on 'Plan' entity. The 'entity_id' attribute specifies the plan idaddonIndicates that this lineitem is based on 'Addon' entity. The 'entity_id' attribute specifies the addon idadhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case
entity_id
optional, string, max chars=100
The identifier of the modelled entity this line item is based on. Will be null for 'adhoc' entity type
discounts
Show attributes[+]
optional, list of discount
The list of discounts applied to this estimate
Discount attributes
amount
in cents, min=0
The amount deducted. The format of this value depends on the kind of currency.
description
optional, string, max chars=250
Description for this deduction.
type
enumerated string
Type of this Discount lineitem
Possible values are
couponRepresents the coupon discount items in invoice. Further the 'entity_id' attribute specifies the coupon id this discount is based oncredit_adjustmentRepresents the Prorated Credits items in invoice. The 'entity_id' attribute will be null in this caseaccount_creditsRepresents the Promotional Credits item in invoice. The 'entity_id' attribute will be null in this case
entity_id
optional, string, max chars=100
When the deduction is due to a coupon, then this is the id of the coupon.
taxes
Show attributes[+]
optional, list of tax
The list of taxes applied to this estimate
Tax attributes
amount
in cents, min=0
The tax amount.
description
optional, string, max chars=250
Description of the tax item.

Create subscription 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

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

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

Input Parameters

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
Parameters for subscription
pass parameters as subscription[<param name>]
subscription[id]
optional, string, max chars=50
A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
subscription[plan_id]
required, string, max chars=100
Identifier of the plan for this subscription
subscription[plan_quantity]
optional, integer, default=1, min=1
Plan quantity for this subscription
subscription[trial_end]
optional, timestamp(UTC) in seconds
The time at which the trial ends for this subscription. Can be specified to override the default trial period.If '0' is passed, the subscription will be activated immediately.
subscription[start_date]
optional, timestamp(UTC) in seconds
The date/time at which the subscription is to start. If not provided, the subscription starts immediately. You can provide a value in the past as well. This is called backdating the subscription creation and is done when the subscription has already been provisioned but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:
  • Backdating is enabled for subscription creation operations.
  • The current day of the month does not exceed the limit set in Chargebee for backdating such operations. This day is typically the day of the month by which the accounting for the previous month must be closed.
  • The date is not more than duration X into the past, where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April, start_date cannot be earlier than 14th February.
subscription[coupon]
optional, string, max chars=100

The id of the coupon. For validating the coupon code provided by the user , use the following codes in combination with the param attribute in the error response.

  • resource_not_found : Returned if the coupon is not present.
  • resource_limit_exhausted : Returned if the coupon has expired or the maximum redemption for the coupon has already been reached.
  • invalid_request : Returned if the coupon is not applicable for the particular plan/addon.
+
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
billing_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
billing_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

+
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
shipping_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
shipping_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

+
customer
Parameters for customer
pass parameters as customer[<param name>]
customer[vat_number]
optional, string, max chars=20
VAT number of this customer. If not provided then taxes are not calculated for the estimate. Applicable only when taxes are configured for the EU or UK region. VAT validation is not done for this.
customer[taxability]
optional, enumerated string, default=taxable
Specifies if the customer is liable for tax
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.
+
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
addons[id][0..n]
optional, string, max chars=100
Identifier of the addon. Multiple addons can be passed.
addons[quantity][0..n]
optional, integer, default=1, min=1
Quantity of the addon. Applicable for addons with pricing_model other than flat_fee.

Returns

estimate
always returned
Resource object representing estimate

Create subscription for a customer estimate

Create a subscription for the existing estimate of a customer.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/customers/__test__5SK2liZoRZxq5Tg18/create_subscription_estimate \
     -G  \
     -u {site_api_key}:\
copy
curl  https://{site}.chargebee.com/api/v1/customers/__test__5SK2liZoRZxq5Tg18/create_subscription_estimate \
     -G  \
     -u {site_api_key}:\

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

Input Parameters

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
Parameters for subscription
pass parameters as subscription[<param name>]
subscription[id]
optional, string, max chars=50
A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
subscription[plan_id]
required, string, max chars=100
Identifier of the plan for this subscription
subscription[plan_quantity]
optional, integer, default=1, min=1
Plan quantity for this subscription
subscription[trial_end]
optional, timestamp(UTC) in seconds
The time at which the trial ends for this subscription. Can be specified to override the default trial period.If '0' is passed, the subscription will be activated immediately.
subscription[start_date]
optional, timestamp(UTC) in seconds
The date/time at which the subscription is to start. If not provided, the subscription starts immediately. You can provide a value in the past as well. This is called backdating the subscription creation and is done when the subscription has already been provisioned but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:
  • Backdating is enabled for subscription creation operations.
  • The current day of the month does not exceed the limit set in Chargebee for backdating such operations. This day is typically the day of the month by which the accounting for the previous month must be closed.
  • The date is not more than duration X into the past, where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April, start_date cannot be earlier than 14th February.
subscription[coupon]
optional, string, max chars=100

The id of the coupon. For validating the coupon code provided by the user , use the following codes in combination with the param attribute in the error response.

  • resource_not_found : Returned if the coupon is not present.
  • resource_limit_exhausted : Returned if the coupon has expired or the maximum redemption for the coupon has already been reached.
  • invalid_request : Returned if the coupon is not applicable for the particular plan/addon.
+
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
shipping_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
shipping_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

+
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
addons[id][0..n]
optional, string, max chars=100
Identifier of the addon. Multiple addons can be passed.
addons[quantity][0..n]
optional, integer, default=1, min=1
Quantity of the addon. Applicable for addons with pricing_model other than flat_fee.

Returns

estimate
always returned
Resource object representing estimate

Update subscription estimate

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.

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

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

Input Parameters

replace_addon_list
optional, boolean
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
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
Parameters for subscription
pass parameters as subscription[<param name>]
subscription[id]
required, string, max chars=50
A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
subscription[plan_id]
optional, string, max chars=100
Identifier of the plan for this subscription
subscription[plan_quantity]
optional, integer, min=1
Represents the plan quantity for this subscription.
subscription[start_date]
optional, timestamp(UTC) in seconds
The new start date of a future subscription. Applicable only for future subscriptions.
subscription[trial_end]
optional, timestamp(UTC) in seconds
The time at which the trial has ended or will end for the subscription. This is only allowed when the subscription status is future, in_trial, or cancelled. Also, the value must not be earlier than changes_scheduled_at or start_date. Note: This parameter can be backdated (set to a value in the past) only when the subscription is in cancelled or in_trial status. Do this to keep a record of when the trial ended in case it ended at some point in the past. When trial_end is backdated, the subscription immediately goes into active or non_renewing status.
subscription[coupon]
optional, string, max chars=100

Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.

Note:

When the coupon ID contains a special character; for example: #, the API returns an error. Make sure that you encode the coupon ID in the path parameter before making an API call.

+
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
billing_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
billing_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

+
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
shipping_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
shipping_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

+
customer
Parameters for customer
pass parameters as customer[<param name>]
customer[vat_number]
optional, string, max chars=20
VAT number of this customer. If not provided then taxes are not calculated for the estimate. Applicable only when taxes are configured for the EU or UK region. VAT validation is not done for this.
+
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
addons[id][0..n]
optional, string, max chars=100
Identifier of the addon. Multiple addons can be passed.
addons[quantity][0..n]
optional, integer, min=1
Quantity of the addon. Applicable for addons with pricing_model other than flat_fee.

Returns

estimate
always returned
Resource object representing estimate

Subscription renewal estimate

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.

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

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

Input Parameters

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.

Returns

estimate
always returned
Resource object representing estimate

Create invoice estimate

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.

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

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

Input Parameters

coupon
optional, string, max chars=100
The 'One Time' coupon to be applied.
+
invoice
Parameters for invoice
pass parameters as invoice[<param name>]
invoice[customer_id]
optional, string, max chars=50
Identifier of the customer for which this invoice needs to be created. Should be specified if 'subscription_id' is not specified.
invoice[subscription_id]
optional, string, max chars=50
Identifier of the subscription for which this invoice needs to be created. Should be specified if 'customer_id' is not specified.(not applicable for consolidated invoice)
invoice[po_number]
optional, string, max chars=100
Purchase Order Number for this invoice.
+
customer
Parameters for customer
pass parameters as customer[<param name>]
customer[vat_number]
optional, string, max chars=20
VAT number of this customer. If not provided then taxes are not calculated for the estimate. Applicable only when taxes are configured for the EU or UK region. VAT validation is not done for this.
customer[taxability]
optional, enumerated string, default=taxable
Specifies if the customer is liable for tax
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.
+
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
billing_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
billing_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

+
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
optional, string, max chars=150
The first name of the contact.
shipping_address[last_name]
optional, string, max chars=150
The last name of the contact.
shipping_address[email]
optional, string, max chars=70
The email address.
shipping_address[company]
optional, string, max chars=250
The company name.
shipping_address[phone]
optional, string, max chars=50
The phone number.
shipping_address[line1]
optional, string, max chars=150
Address line 1
shipping_address[line2]
optional, string, max chars=150
Address line 2
shipping_address[line3]
optional, string, max chars=150
Address line 3
shipping_address[city]
optional, string, max chars=50
The name of the city.
shipping_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
shipping_address[state]
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
shipping_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
shipping_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

+
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
addons[id][0..n]
optional, string, max chars=100
Identifier of the addon. Multiple addons can be passed.
addons[quantity][0..n]
optional, integer, default=1, min=1
Quantity of the addon. Applicable for addons with pricing_model other than flat_fee.
+
charges
Parameters for charges. Multiple charges can be passed by specifying unique indices.
pass parameters as charges[<param name>][<idx:0..n>]
charges[amount][0..n]
optional, in cents, min=1
The amount to be charged. The unit depends on the type of currency.
charges[description][0..n]
optional, string, max chars=250
Description for this charge

Returns

estimate
always returned
Resource object representing estimate