'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 API.
Note:
{
"created_at": 1517505710,
"invoice_estimate": {
"amount_due": 895,
"amount_paid": 0,
"credits_applied": 0,
"currency_code": "USD",
"customer_id": "__test__KyVnHhSBWl2E82aS",
"date": 1517505710,
"line_item_discounts": [],
"line_item_taxes": [],
"line_items": [{
"amount": 895,
"customer_id": "__test__KyVnHhSBWl2E82aS",
"date_from": 1517505710,
"date_to": 1519924910,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__KyVnHhSBWl2Eq2aU",
"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": 1519924910,
"object": "subscription_estimate",
"status": "active"
}
}
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
).contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to renew
.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to cancel
.active
contract terms, this is a predicted value. The value depends on the type of currency. If the subscription was imported with the contract term, then this value includes the value passed for total_amount_raised
.contract_end
, during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure.line_item
. The value is in major units of the currency. Returned when the line_item
is quantity-based and multi-decimal pricing is enabled.line_item
is quantity-based and multi-decimal pricing is enabled.line_item
, in major units of the currency. Typically equals to unit_amount_in_decimal
x quantity_in_decimal
. Returned when multi-decimal pricing is enabled.stairtstep
pricing , or the price of each unit in the tier if the charge model is tiered
/volume
pricing.ending_unit_in_decimal
of the next lower tier. Returned only when the line_items.pricing_model
is tiered
, volume
or stairstep
and multi-decimal pricing is enabled.starting_unit_in_decimal
of the next higher tier. Returned only when the line_items.pricing_model
is tiered
, volume
or stairstep and multi-decimal pricing is enabled.line_item
is quantity-based and multi-decimal pricing is enabled.pricing_model
is tiered
or volume
. When the pricing_model
is stairstep
, it is the decimal representation of the total price for line_item
. The value is in major units of the currency. Returned when the line_item
is quantity-based and multi-decimal pricing is enabled.line_item
. The value is in major units of the currency. Returned when the line_item
is quantity-based and multi-decimal pricing is enabled.line_item
is quantity-based and multi-decimal pricing is enabled.line_item
, in major units of the currency. Typically equals to unit_amount_in_decimal
x quantity_in_decimal
. Returned when multi-decimal pricing is enabled.stairtstep
pricing , or the price of each unit in the tier if the charge model is tiered
/volume
pricing.ending_unit_in_decimal
of the next lower tier. Returned only when the line_items.pricing_model
is tiered
, volume
or stairstep
and multi-decimal pricing is enabled.starting_unit_in_decimal
of the next higher tier. Returned only when the line_items.pricing_model
is tiered
, volume
or stairstep and multi-decimal pricing is enabled.line_item
is quantity-based and multi-decimal pricing is enabled.pricing_model
is tiered
or volume
. When the pricing_model
is stairstep
, it is the decimal representation of the total price for line_item
. The value is in major units of the currency. Returned when the line_item
is quantity-based and multi-decimal pricing is enabled.unit_amount_in_decimal
x quantity_in_decimal
. Returned when multi-decimal pricing is enabled.stairtstep
pricing , or the price of each unit in the tier if the charge model is tiered
/volume
pricing.ending_unit_in_decimal
of the next lower tier. Returned only when the line_items.pricing_model
is tiered
, volume
or stairstep
and multi-decimal pricing is enabled.starting_unit_in_decimal
of the next higher tier. Returned only when the line_items.pricing_model
is tiered
, volume
or stairstep and multi-decimal pricing is enabled.line_item
is quantity-based and multi-decimal pricing is enabled.pricing_model
is tiered
or volume
. When the pricing_model
is stairstep
, it is the decimal representation of the total price for line_item
. The value is in major units of the currency. Returned when the line_item
is quantity-based and multi-decimal pricing is enabled.Generates an estimate for the 'create subscription' operation. This is similar to the Create Subscription API but no subscription will be created, only an estimate for this operation is created.
In the response,
If the subscription is created in trial/future states, estimate.invoice_estimate will not be present as no immediate invoice would be generated. However, estimate.next_invoice_estimate will be returned which is a preview of the invoice that would be generated at a later date when the subscription becomes 'active'.
Tip
Set the customer[taxability]
attribute as true
and provide any other necessary parameters to compute taxes. Otherwise tax is exempted for the estimate.
curl https://{site}.chargebee.com/api/v2/estimates/create_subscription \ -u {site_api_key}:\ -d subscription[plan_id]="no_trial" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US"
curl https://{site}.chargebee.com/api/v2/estimates/create_subscription \ -u {site_api_key}:\ -d subscription[plan_id]="no_trial" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US"
billing_cycles
or a custom value depending on the site configuration.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
).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
).true
then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.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.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to renew
.contract_end
, during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure.period
. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.active
or non-renewing
status. Once set, the value can't be changed. (Addon trial periods must be enabled by Chargebee Support.).curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl2XD2aV/create_subscription_estimate \ -G \ -u {site_api_key}:\
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl2XD2aV/create_subscription_estimate \ -G \ -u {site_api_key}:\
billing_cycles
or a custom value depending on the site configuration.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
).contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to renew
.contract_end
, during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure.period
. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.active
or non-renewing
status. Once set, the value can't be changed. (Addon trial periods must be enabled by Chargebee Support.).Generates an estimate for the 'update subscription' operation. The input will be similar to the Update Subscription API but subscription will not be updated, only an estimate will be created.
In the response,
The generated invoice_estimate/next_invoice_estimate will include all the balances - Promotional Credits, Refundable Credits, and Excess Payments - if any. If you don’t want these balances to be included you can specify 'false' for the parameter use_existing_balances.
Note: If you have configured EU VAT or Customized taxes, you need to specify the applicable parameters for calculating taxes - billing_address[], shipping_address[], customer[vat_number], customer[taxability] etc. Otherwise tax calculation will be ignored.
curl https://{site}.chargebee.com/api/v2/estimates/update_subscription \ -u {site_api_key}:\ -d subscription[id]="__test__KyVnHhSBWl3M42aj" \ -d subscription[plan_id]="plan1" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US"
curl https://{site}.chargebee.com/api/v2/estimates/update_subscription \ -u {site_api_key}:\ -d subscription[id]="__test__KyVnHhSBWl3M42aj" \ -d subscription[plan_id]="plan1" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US"
terms_to_charge
is inclusive of this new term. See description for the force_term_reset
parameter to learn more about when a subscription term is reset.reactivate
parameter, this is the date/time at which the subscription should be reactivated.true
then the existing coupon_ids
list for the subscription is replaced by the one provided. If false
then the provided list gets added to the existing coupon_ids
.true
will have the subscription reset its term to the current date (provided end_of_term
is false).cancelled
subscriptions. When passed as true
, the canceled subscription is activated; otherwise subscription changes are made without changing its status
. If not passed, subscription will be activated only if subscription_items
is passed.future
subscription. Applicable only for future
subscriptions.0
to have no trial period.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
).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
).true
then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.period
. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.replace_addon_list
. (Addon trial periods must be enabled by Chargebee Support.).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.
In the response,
The generated invoice estimate will include all the balances - Promotional Credits, Refundable Credits, and Excess Payments - if any. If you don’t want these balances to be included you can specify 'false' for the parameter use_existing_balances.
To exclude the delayed charges from the invoice estimate, specify 'false' for the parameter include_delayed_charges.
Note:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkzpS2Zo/renewal_estimate \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkzpS2Zo/renewal_estimate \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkjcSAl6gBw1/advance_invoice_estimate \ -u {site_api_key}:\ -d invoice_immediately="false" \ -d terms_to_charge=3
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkjcSAl6gBw1/advance_invoice_estimate \ -u {site_api_key}:\ -d invoice_immediately="false" \ -d terms_to_charge=3
schedule_type = immediate
: the number of future billing cycles to be invoiced in advance. The invoicing is done for the remaining_billing_cycles
of the subscription if that is less than terms_to_charge
.schedule_type = fixed_intervals
: The number of future billing cycles in one interval. The schedule is created such that the total number of billing cycles in the schedule does not exceed the remaining_billing_cycles of the subscription.unbilled_charges
. Applicable only when schedule_type
is immediate
.terms_to_charge
.specific_datesCharge on specific dates. For each date, specify the number of billing cycles to charge for. Up to 5 dates can be configured.fixed_intervalsCharge at fixed intervals of time. Specify the number of billing cycles that constitute an interval and the number of days before each interval that the invoice should be generated. Also specify when the schedule should end.remaining_billing_cycles
of the subscription. This parameter is applicable only when fixed_interval_schedule[end_schedule_on]
= after_number_of_intervals
.specified number of times
.specific_dateEnd the advance invoicing schedule on a specific date
.subscription_endAdvance invoices are generated for as long as the subscription is active.fixed_interval_schedule[end_schedule_on]
= specific_date
.schedule_type
is specific_dates.schedule_type
is specific_dates
. Regenerates the invoice for the current term of the subscription. The subscription must have status
as active
or non_renewing
. This operation is not allowed when any of the following conditions hold true for the subscription:
status
is not voided
. Returns an estimate
object with one of the following components depending on the value of invoice_immediately
.
true
: an invoice_estimate
object that corresponds to the regenerated invoice. false
: a list of unbilled_charge_estimate
objects corresponding to all the unbilled charges created for the current term of the subscription.curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnOuSHufvfo16/regenerate_invoice_estimate \ -X POST \ -u {site_api_key}:\ -d invoice_immediately="true"
date_from
and date_to
. Should not be passed without date_from
and date_to
.false
to leave the current term charge for the subscription as unbilled. Once you have done this for all suitable subscriptions of the customer, call Create an invoice for unbilled charges to invoice them.Estimate of the upcoming scheduled invoices (subscription activations, renewals etc) of a customer. For now preview of the invoices generated on the immediate upcoming date is supported. Say a customer has couple of subscription renewals scheduled on Jan,10th and another subscription renewal scheduled on Jan,15th. This API gives the preview of all the invoices scheduled to be generated on Jan,10th (immediate upcoming date).
In the response:
Note: If consolidated invoicing is enabled you may use this API to test whether upcoming renewals are consolidated.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl2pw2aa/upcoming_invoices_estimate \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl2pw2aa/upcoming_invoices_estimate \ -u {site_api_key}:
Generates an estimate for the 'change term end' operation. This is similar to the Change term end API but the subscription’s term end will not be changed, only an estimate for this operation is created. This is applicable only for subscriptions in ‘in-trial’, ‘active’ and ‘non-renewing’ states.
In the response,
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkzRq2Zh/change_term_end_estimate \ -u {site_api_key}:\ -d term_ends_at=1566697500
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkzRq2Zh/change_term_end_estimate \ -u {site_api_key}:\ -d term_ends_at=1566697500
Generates an estimate for the 'cancel subscription' operation. This is similar to the Cancel a subscription API, but the subscription will not be cancelled. Only an estimate for this operation is created.
In the response,
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkz4Y2Za/cancel_subscription_estimate \ -X POST \ -u {site_api_key}:\ -d end_of_term="true"
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkz4Y2Za/cancel_subscription_estimate \ -X POST \ -u {site_api_key}:\ -d end_of_term="true"
true
if you want to cancel the subscription at the end of the current subscription billing cycle.end_of_term
is passed as true
.terminate_immediately
immediately does the following:status
to terminated
.end_of_contract_term
Sets the contract_term[action_at_term_end]
to cancel
. In other words, the contract term is not renewed and the subscription is canceled at the end of the contract term.id
of the event-based addon that represents the termination fee.This API provides an estimate of the details pertaining to the pause_subscription operation. It returns attributes such as pause_date, resume_date, etc. This is similar to the Pause a subscription API, but the subscription will not be paused. Only an estimate for this operation is created.
In the response,
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWl1SO2aC/pause_subscription_estimate \ -X POST \ -u {site_api_key}:\ -d pause_option="specific_date" \ -d subscription[pause_date]=1566698400
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWl1SO2aC/pause_subscription_estimate \ -X POST \ -u {site_api_key}:\ -d pause_option="specific_date" \ -d subscription[pause_date]=1566698400
paused
state, it is the date/time when the subscription was paused.Generates an estimate for the 'resume subscription' operation. This is similar to the Resume a subscription API, but the subscription will not be resumed. Only an estimate for this operation is created.
In the response,
++What is an "in-term resumption"?
An “in-term resumption” is when the resumption happens within the billing term of the subscription.
The generated invoice_estimate/next_invoice_estimate will include all the balances - Promotional Credits, Refundable Credits, and Excess Payments - if any.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWl1p52aJ/resume_subscription_estimate \ -X POST \ -u {site_api_key}:\ -d resume_option="immediately"
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWl1p52aJ/resume_subscription_estimate \ -X POST \ -u {site_api_key}:\ -d resume_option="immediately"
Generates an estimate for the 'create a gift' operation. This is similar to the Create a gift API, but the gift subscription will not be created. Only an estimate for this operation is created.
In the response,
curl https://{site}.chargebee.com/api/v2/estimates/gift_subscription \ -u {site_api_key}:\ -d subscription[plan_id]="GiftPlan$100" \ -d gifter[customer_id]="gifter" \ -d gifter[signature]="Sam" \ -d gift_receiver[customer_id]="receiver" \ -d gift_receiver[first_name]="James" \ -d gift_receiver[last_name]="William" \ -d gift_receiver[email]="james@user.com"
curl https://{site}.chargebee.com/api/v2/estimates/gift_subscription \ -u {site_api_key}:\ -d subscription[plan_id]="GiftPlan$100" \ -d gifter[customer_id]="gifter" \ -d gifter[signature]="Sam" \ -d gift_receiver[customer_id]="receiver" \ -d gift_receiver[first_name]="James" \ -d gift_receiver[last_name]="William" \ -d gift_receiver[email]="james@user.com"
true
, the claim happens automatically. When not passed, the default value in the site settings is used.true
, indicates that the gift does not expire. Do not pass or pass as false
when auto_claim
is set.
.scheduled_at
. If the gift is not claimed within claim_expiry_date
, it will expire and the subscription will move to cancelled
state. When not passed, the value specified in the site settings will be used.
Pass as NULL
or do not pass when auto_claim
or no_expiry
are set.device_session_id
and fraud_merchant_id
as an input to fingerprint
. Here’s a sample to it.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
).state_code
is provided.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.
In the response,
curl https://{site}.chargebee.com/api/v2/estimates/create_invoice \ -u {site_api_key}:\ -d invoice[customer_id]="__test__KyVnHhSBWl0D02Zw" \ -d charges[amount][0]=1000 \ -d charges[description][0]="Adhoc charge"
curl https://{site}.chargebee.com/api/v2/estimates/create_invoice \ -u {site_api_key}:\ -d invoice[customer_id]="__test__KyVnHhSBWl0D02Zw" \ -d charges[amount][0]=1000 \ -d charges[description][0]="Adhoc charge"
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
).state_code
is provided.