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.
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.
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
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
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
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
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
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.
optional, integer, min=0 Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
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.
optional, boolean, default=false If true, all the existing balances - promotional credits, refundable credits and excess payments - will be included for the invoice estimate.
optional, integer, min=0 Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
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.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
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.
optional, boolean, default=false If true, all the existing balances - promotional credits, refundable credits and excess payments - will be included for the invoice 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.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
optional, boolean, default=false If true, all the existing balances - promotional credits, refundable credits and excess payments - will be included for the 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.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
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.