During the process of signing up customers to subscriptions, use the Estimates API to evaluate the details of the purchase before actually signing them up. The details returned by the API include the invoice amounts, next billing date and unbilled charges.
For example, consider that you are creating a new subscription or update an existing one. Use the Estimates API before that to deduce the details such as the amount the customer would be charged, the state the subscription would be in after creation or updation, and so on.
If you have configured the Avalara integration, Chargebee retrieves the tax amount from Avalara for the invoice. This counts against your Avalara API limits.
Sample EstimateJSON
Estimates attributes
Represents the subscription details when the 'estimate' operations are invoked.
Is a list of estimated subscriptions i.e., an array of subscription_estimate objects. It is generated when 'Create an estimate for purchase' operation is invoked
Represents the preview of the invoice generated immediately when the 'estimate' operations are invoked.
Is a list of estimated invoices i.e., an array of invoice_estimate objects. It is generated when 'Create an estimate for unbilled charges' operation is invoked
payment_schedule_estimate resource is used to hold the details related to payment schedules for an invoice. It will contain list of payment_schedules resource.
Represents the preview of the invoice generated at term end when the 'estimate' operations are invoked.
Represents the preview of the credit-notes generated during 'estimate' operation. Currently applicable only for the 'Update Subscription Estimate' operation.
Subscription estimate attributes
The status of the subscription.
The subscription is scheduled to start at a future date.
The subscription is in trial.
The subscription is active and will be charged for automatically based on the items in it.
The subscription will be canceled at the end of the current term.
The subscription is paused. The subscription will not renew while in this state.
The subscription has been canceled and is no longer in service.
The subscription has been transferred to another business entity within the organization.
Applicable only when End-of-trial Action has been enabled for the site. Whenever the subscription has a trial period, this attribute (parameter) is returned (required) and specifies the operation to be carried out for the subscription once the trial ends.
This is the default value. The action configured for the site at the time when the trial ends, takes effect.
The action configured for the site at the time when the trial ends, takes effect.
The subscription activates and charges are raised for non-metered items.
The subscription cancels.
Date on which the next billing happens. This will be null for non-renewing and cancelled subscriptions.
The date on which subscription will be paused. Applicable only to paused or scheduled pause subscriptions
The date on which subscription will be resumed. Applicable only to paused or scheduled pause subscriptions
Represents the shipping address when the 'estimate' operations are invoked.
Invoice estimate attributes
Whether or not the estimate for the invoice is recurring. Will be 'true' or 'false' for subscription related estimates.
The price type of this invoice.
All amounts in the document are exclusive of tax.
All amounts in the document are inclusive of tax.
Existing outstanding payments if any, applied to this invoice in cents.
Indicates the rounded-off amount. For example, if your invoice amount is $99.99, and the amount is rounded off to $100.00, in this case, $100.00 is your invoice amount, $0.01 is the round_off_amount.
If there is no round-off amount
, it will display 0
.
A unique identifier for the customer this invoice belongs to
Payment schedule estimate attributes
The identifier of the payment_schedule_scheme
, used to create the payment schedules.
Specifies the modelled entity this payment schedule is based on
invoice
The identifier of the modelled entity this payment schedule is based on.
total maximum amount that this payment schedule is allowed to collect
The currency code (ISO 4217 format) of the transaction amount.
Credit note estimate attributes
Credit note type. Learn more about credit note types.
Adjustment Credit Note
Refundable Credit Note
Store Credit Note
The price type of this credit note.
All amounts in the document are exclusive of tax.
All amounts in the document are inclusive of tax.
Indicates the rounded-off amount. For example, if your invoice amount is $99.99, and the amount is rounded off to $100.00, in this case, $100.00 is your invoice amount, $0.01 is the round_off_amount.
If there is no round-off amount
, it will display 0
.
A unique identifier for the customer this credit note belongs to
Unbilled charge estimate attributes
A unique identifier for the subscription this charge belongs to.
The pricing scheme for this line item.
A fixed price that is not quantity-based.
A fixed price per unit quantity.
There are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.
The per unit price is based on the tier that the total quantity falls in.
A quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in.
Total amount of this charge. Typically equals to unit amount x quantity.
Specifies the modelled entity this line item is based on.
Indicates that this lineitem is based on 'Plan Setup' charge. The 'entity_id' attribute specifies the plan id
Indicates that this lineitem is based on 'Plan' entity. The 'entity_id' attribute specifies the plan id
Indicates that this lineitem is based on 'Addon' entity. The 'entity_id' attribute specifies the addon id
Indicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case
The identifier of the modelled entity this charge is based on. Will be null for 'adhoc' entity type.
Will be true if the charge has been voided. Usually the unbilled charge will be voided and revised to different charges(s) during proration.
Timestamp indicating the date and time this charge got voided.
The decimal representation of the amount for the charge, in major units of the currency. Typically equals to unit_amount_in_decimal
x quantity_in_decimal.
Returned when multi-decimal pricing
is enabled.
The decimal representation of the quantity of this entity. Returned when the entity is quantity-based and multi-decimal pricing is enabled.
The decimal representation of the unit amount for the entity. The value is in major units of the currency. Returned when the entity is quantity-based and multi-decimal pricing is enabled.
Timestamp indicating when the unbilled charge was last updated
The value of this parameter will be true if it is a recurring unbilled charge for a future term.
The ID of the business entity created for the site. For Product Catalog 1.0, all the site data is tied to this business entity.
Note
Multiple Business Entities is a feature available only on Product Catalog 2.0.