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, 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 ]

{ "created_at": 1484646432, "recurring": true, "subscription_id": "test123", "term_ends_at": 1487324832, "collect_now": false, "price_type": "tax_exclusive", "amount": 900, "credits_applied": 0, "amount_due": 0, "object": "estimate", "sub_total": 900, "line_items": [ { "date_from": 1487324832, "date_to": 1489744032, "unit_amount": 900, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 900, "description": "Sample", "type": "charge", "entity_type": "plan", "entity_id": "basic" }, {..} ] }
created_at
The time at which this estimate got generated.
timestamp(UTC) in seconds
recurring
Will be 'true' for subscription related estimates.
boolean, default=true
subscription_id
Applicable only for subsctiption related estimates. The identifier of the subscription this estimate belongs to.
optional, string, max chars=100
subscription_status
Applicable only for subsctiption related estimates. The post-operation status of the subscription.
optional, enumerated string
Possible values are
futureThe Subscription is scheduled to start in a future date.in_trialThe subscription is in trial.activeThe subscription is in active state and will be charged at start of each term based on the recurring items(plan & addons etc.,).non_renewingThe subscription will be cancelled at end of the current term.cancelledThe subscription has been cancelled. No new recurring actions will take place, but any pending payments will be collected.
term_ends_at
Applicable only for subsctiption related estimates. End of the current billing term.
optional, timestamp(UTC) in seconds
collect_now
'true' means the estimate amount needs to be collected immediately, whereas 'false' means the estimate amount needs to be collected at the term-end.
boolean
price_type
The price type of the invoice.
enumerated string, default=tax_exclusive
Possible values are
tax_exclusiveAll amounts in the document are exclusive of tax.tax_inclusiveAll amounts in the document are inclusive of tax.
amount
Total estimate amount in cents. The 'collect_now' field indicates when this amount needs to be collected.
in cents, default=0, min=0
credits_applied
credits applied to this invoice in cents.
in cents, default=0, min=0
amount_due
Invoice amount due in cents.
in cents, default=0, min=0
sub_total
The sub-total amount.
in cents, min=0
line_items
Show attributes[+]
The list of items in this estimate.
optional, list of line_item
Line item attributes
date_from
Start date of this lineitem.
timestamp(UTC) in seconds
date_to
End date of this lineitem.
timestamp(UTC) in seconds
unit_amount
Unit amount of the lineitem.
in cents
quantity
Quantity of the recurring item which is represented by this lineitem.
optional, integer, default=1
amount
Total amount of this lineitem. Typically equals to unit amount x quantity.
optional, in cents
is_taxed
Specifies whether this line item is taxed or not.
boolean, default=false
tax
The tax amount charged for this item.
optional, in cents, default=0, min=0
tax_rate
Rate of tax used to calculate tax for this lineitem.
optional, double, min=0.0, max=100.0
description
Detailed description about this lineitem.
string, max chars=250
type
Type of this lineitem. This along with 'entity_type' and 'entity_id' attributes consitutes the meta information of this lineitem.
enumerated string
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 on.prorated_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 on.setup_chargeRepresents the 'setup charge' lineitem in invoice - which is a one-time charge included only in the first invoice of the subscription.
entity_type
Specifies the modelled entity (plan / addon etc) this lineitem is based on.
enumerated string
Possible values are
planIndicates that this lineitem is based on 'Plan' entity. The 'entity_id' attribute specifies the plan id.addonIndicates that this lineitem is based on 'Addon' entity. The 'entity_id' attribute specifies the addon id.adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case.
entity_id
The identifier of the modelled entity this lineitem is based on. Will be null for 'adhoc' entity type.
optional, string, max chars=100
discounts
Show attributes[+]
The list of discounts applied to this estimate.
optional, list of discount
Discount attributes
amount
Discount amount.
in cents, min=0
description
Detailed description of this discount line item.
optional, string, max chars=250
type
Type of this Discount lineitem.
enumerated string
Possible values are
couponRepresents the coupon discount items in invoice. Further the 'entity_id' attribute specifies the coupon id this discount is based on.credit_adjustmentRepresents the Prorated Credits items in invoice. The 'entity_id' attribute will be null in this case.account_creditsRepresents the Promotional Credits item in invoice. The 'entity_id' attribute will be null in this case.
entity_id
The identifier of the modelled entity this lineitem is bases on. Will be null for 'Prorated Credits' & 'Promotional Credits'.
optional, string, max chars=100
The list of taxes applied to this estimate.
optional, list of tax
Tax attributes
amount
The tax amount.
in cents, min=0
description
Description of the tax item.
optional, string, max chars=250
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]="basic" \
     -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]="basic" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

Sample Response [ JSON ]

{"estimate": { "created_at": 1484646489, "recurring": true, "subscription_status": "in_trial", "term_ends_at": 1487324889, "collect_now": false, "price_type": "tax_exclusive", "amount": 900, "credits_applied": 0, "amount_due": 900, "object": "estimate", "sub_total": 900, "line_items": [ { "date_from": 1487324889, "date_to": 1489744089, "unit_amount": 900, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 900, "description": "sample plan", "type": "charge", "entity_type": "plan", "entity_id": "basic" }, {..} ] }}

URL Format POST

https://{site}.chargebee.com/api/v1/estimates/create_subscription
billing_cycles
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
subscription
Parameters for subscription
pass parameters as subscription[<param name>]
subscription[id]
A unique identifier to identify the subscription. You will use this to perform all operations on this subscription.
optional, string, max chars=50
subscription[plan_id]
Identifier of the plan for this subscription.
required, string, max chars=100
subscription[plan_quantity]
Plan quantity for this subscription.
optional, integer, default=1, min=1
subscription[start_date]
Allows you to specify a future date or a past date on which the subscription starts.Past dates can be entered in case the subscription has already started. Any past date entered must be within the current billing cycle/plan term. The subscription will start immediately if this parameter is not passed.
optional, timestamp(UTC) in seconds
subscription[trial_end]
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.
optional, timestamp(UTC) in seconds
subscription[coupon]

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.

optional, string, max chars=50
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[state_code]
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
billing_address[zip]
Zip or Postal code.
optional, string, max chars=20
billing_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[state_code]
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
shipping_address[zip]
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
customer
Parameters for customer
pass parameters as customer[<param name>]
customer[vat_number]
VAT number of this customer. VIES validation will not happen for this parameter.
optional, string, max chars=20
customer[taxability]
Specifies if the customer is liable for tax.
optional, enumerated string, default=taxable
Possible values are
taxableCustomer is taxable.exemptCustomer is exempted from tax.
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]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
addons[quantity][0..n]
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1
Resource object representing estimate.
always returned

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]="5cDfREwp3I5lJ" \
     -d subscription[plan_id]="basic" \
     -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]="5cDfREwp3I5lJ" \
     -d subscription[plan_id]="basic" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

Sample Response [ JSON ]

{"estimate": { "created_at": 1484646489, "recurring": true, "subscription_id": "5cDfREwp3I5lJ", "subscription_status": "active", "term_ends_at": 1487159213, "collect_now": false, "price_type": "tax_exclusive", "amount": 900, "credits_applied": 0, "amount_due": 900, "object": "estimate", "sub_total": 900, "line_items": [ { "date_from": 1487159213, "date_to": 1489578413, "unit_amount": 900, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 900, "description": "sample plan", "type": "charge", "entity_type": "plan", "entity_id": "basic" }, {..} ] }}

URL Format POST

https://{site}.chargebee.com/api/v1/estimates/update_subscription
billing_cycles
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
replace_addon_list
Should be true if the existing addons should be replaced with the ones that are being passed.
optional, boolean
prorate
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.
optional, boolean
end_of_term
You can specify when you want to update the subscription.
optional, boolean
include_delayed_charges
If true, all the unbilled charges will be included for the invoice estimate.
optional, boolean, default=false
subscription
Parameters for subscription
pass parameters as subscription[<param name>]
subscription[id]
A unique identifier to identify the subscription. You will use this to perform all operations on this subscription.
required, string, max chars=50
subscription[plan_id]
Identifier of the plan for this subscription.
optional, string, max chars=100
subscription[plan_quantity]
Represents the plan quantity for this subscription.
optional, integer, min=1
subscription[start_date]
Applicable only for 'future' subscriptions. The new start date of the 'future' subscription.
optional, timestamp(UTC) in seconds
subscription[trial_end]
The time at which the trial should end for this subscription. Can be specified to override the default trial period defined in plan. If '0' is passed, the subscription will be activated immediately.
optional, timestamp(UTC) in seconds
subscription[coupon]
Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
optional, string, max chars=50
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[state_code]
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
billing_address[zip]
Zip or Postal code.
optional, string, max chars=20
billing_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[state_code]
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
shipping_address[zip]
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
customer
Parameters for customer
pass parameters as customer[<param name>]
customer[vat_number]
VAT number of this customer. VIES validation will not happen for this parameter.
optional, string, max chars=20
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]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
addons[quantity][0..n]
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1
Resource object representing estimate.
always returned

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/5cDfREwp3I5lJ/renewal_estimate \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/subscriptions/5cDfREwp3I5lJ/renewal_estimate \
     -u {site_api_key}:

Sample Response [ JSON ]

{"estimate": { "created_at": 1484646489, "recurring": true, "subscription_id": "5cDfREwp3I5lJ", "subscription_status": "active", "term_ends_at": 1487159213, "collect_now": false, "price_type": "tax_exclusive", "amount": 900, "credits_applied": 0, "amount_due": 900, "object": "estimate", "sub_total": 900, "line_items": [ { "date_from": 1487159213, "date_to": 1489578413, "unit_amount": 900, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 900, "description": "sample plan", "type": "charge", "entity_type": "plan", "entity_id": "basic" }, {..} ] }}

URL Format GET

https://{site}.chargebee.com/api/v1/subscriptions/{subscription_id}/renewal_estimate
include_delayed_charges
If true, all the unbilled charges will be included for the invoice estimate.
optional, boolean, default=true
Resource object representing estimate.
always returned