Estimates

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.

API Index URL

https://[site].chargebee.com/api/v2/estimates

Estimates attributes

created_at

required, timestamp(UTC) in seconds

The time at which this estimate got generated

subscription_estimate

Represents the subscription details when the 'estimate' operations are invoked.

subscription_estimates

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

invoice_estimate

Represents the preview of the invoice generated immediately when the 'estimate' operations are invoked.

invoice_estimates

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_estimates

payment_schedule_estimate is used to hold the details related to payment schedules for an invoice. It will contain a list of payment_schedules resources.

next_invoice_estimate

Represents the preview of the invoice generated at term end when the 'estimate' operations are invoked.

credit_note_estimates

Represents the preview of the credit-notes generated during 'estimate' operation. Currently applicable only for the 'Update Subscription Estimate' operation.

unbilled_charge_estimates

Represents the preview of the unbilled charges generated during 'estimate' operation. Currently not applicable for the 'Subscription renewal estimate' operation.

Subscription estimate attributes

optional, string, max chars=50

The identifier of the subscription

currency_code

required, string, max chars=3

The currency code (ISO 4217 format) of the subscription.

status

optional, enumerated string

The status of the subscription.

Enum Values

future

The subscription is scheduled to start at a future date.

in_trial

The subscription is in trial.

active

The subscription is active and will be charged for automatically based on the items in it.

non_renewing

The subscription will be canceled at the end of the current term.

paused

The subscription is paused. The subscription will not renew while in this state.

cancelled

The subscription has been canceled and is no longer in service.

transferred

The subscription has been transferred to another business entity within the organization.

trial_end_action

optional, enumerated string

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.

Enum Values

site_default

This is the default value. The action configured for the site at the time when the trial ends, takes effect.

plan_default

The action configured for the site at the time when the trial ends, takes effect.

activate_subscription

The subscription activates and charges are raised for non-metered items.

cancel_subscription

The subscription cancels.

next_billing_at

optional, timestamp(UTC) in seconds

Date on which the next billing happens. This will be null for non-renewing and cancelled subscriptions.

pause_date

optional, timestamp(UTC) in seconds

The date on which subscription will be paused. Applicable only to paused or scheduled pause subscriptions

resume_date

optional, timestamp(UTC) in seconds

The date on which subscription will be resumed. Applicable only to paused or scheduled pause subscriptions

shipping_address

Represents the shipping address when the 'estimate' operations are invoked.

contract_term

Represents the contract terms when the 'estimate' operations are invoked.

Invoice estimate attributes

recurring

required, boolean, default=true

Whether or not the estimate for the invoice is recurring. Will be 'true' or 'false' for subscription related estimates.

price_type

required, enumerated string, default=tax_exclusive

The price type of this invoice.

Enum Values

tax_exclusive

All amounts in the document are exclusive of tax.

tax_inclusive

All amounts in the document are inclusive of tax.

currency_code

required, string, max chars=3

The currency code (ISO 4217 format) of the invoice.

sub_total

required, in cents, min=0

Invoice sub-total in cents.

total

optional, in cents, default=0, min=0

Invoice total in cents.

credits_applied

optional, in cents, default=0, min=0

credits applied to this invoice in cents.

amount_paid

optional, in cents, default=0, min=0

Existing outstanding payments if any, applied to this invoice in cents.

amount_due

optional, in cents, default=0, min=0

Invoice amount due in cents

round_off_amount

optional, in cents, min=0

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 .

customer_id

optional, string, max chars=100

A unique identifier for the customer this invoice belongs to

discounts

The list of discounts applied to this estimate

taxes

The list of taxes applied to this estimate

line_items[0..n]

Parameters for line_items. Multiple line_items can be passed by specifying unique indices.

pass parameters as line_items[<param name>][<idx:0..n>]

line_item_tiers[0..n]

Parameters for line_item_tiers. Multiple line_item_tiers can be passed by specifying unique indices.

pass parameters as line_item_tiers[<param name>][<idx:0..n>]

line_item_discounts[0..n]

Parameters for line_item_discounts. Multiple line_item_discounts can be passed by specifying unique indices.

pass parameters as line_item_discounts[<param name>][<idx:0..n>]

line_item_taxes[0..n]

Parameters for line_item_taxes. Multiple line_item_taxes can be passed by specifying unique indices.

pass parameters as line_item_taxes[<param name>][<idx:0..n>]

line_item_credits[0..n]

Parameters for line_item_credits. Multiple line_item_credits can be passed by specifying unique indices.

pass parameters as line_item_credits[<param name>][<idx:0..n>]

line_item_addresses[0..n]

Parameters for line_item_addresses. Multiple line_item_addresses can be passed by specifying unique indices.

pass parameters as line_item_addresses[<param name>][<idx:0..n>]

Payment schedule estimate attributes

required, string, max chars=40

An auto-generated unique identifier for the payment schedule.

scheme_id

required, string, max chars=40

The identifier of the payment_schedule_scheme , used to create the payment schedules.

entity_type

required, enumerated string

Specifies the modeled entity that the payment schedule is based on.

Enum Values

invoice

Represents an invoice.

entity_id

optional, string, max chars=50

The identifier of the modeled entity that this payment schedule is based on.

amount

required, in cents, min=0

An amount that this payment schedule is able to collect.

currency_code

optional, string, max chars=3

The currency code (ISO 4217 format) of the transaction amount.

schedule_entries

List of schedule entries

Credit note estimate attributes

reference_invoice_id

required, string, max chars=50

The reference invoice id

type

required, enumerated string

Credit note types. Learn more about credit note types.

Enum Values

adjustment

Adjustment Credit Note

refundable

Refundable Credit Note

store

Store Credit Note

price_type

required, enumerated string, default=tax_exclusive

The price type of this credit note.

Enum Values

tax_exclusive

All amounts in the document are exclusive of tax.

tax_inclusive

All amounts in the document are inclusive of tax.

currency_code

required, string, max chars=3

The currency code (ISO 4217 format) of the credit note.

sub_total

required, in cents, min=0

Invoice sub-total in cents.

total

required, in cents, min=0

Credit note total in cents.

amount_allocated

required, in cents, min=0

Allocated credits in cents.

amount_available

required, in cents, min=0

Remaining credits in cents

round_off_amount

optional, in cents, min=0

customer_id

optional, string, max chars=100

A unique identifier for the customer this credit note belongs to

discounts

The list of discounts applied to this estimate

taxes

The list of taxes applied to this estimate

line_items[0..n]

Parameters for line_items. Multiple line_items can be passed by specifying unique indices.

pass parameters as line_items[<param name>][<idx:0..n>]

line_item_tiers[0..n]

Parameters for line_item_tiers. Multiple line_item_tiers can be passed by specifying unique indices.

pass parameters as line_item_tiers[<param name>][<idx:0..n>]

line_item_discounts[0..n]

Parameters for line_item_discounts. Multiple line_item_discounts can be passed by specifying unique indices.

pass parameters as line_item_discounts[<param name>][<idx:0..n>]

line_item_taxes[0..n]

Parameters for line_item_taxes. Multiple line_item_taxes can be passed by specifying unique indices.

pass parameters as line_item_taxes[<param name>][<idx:0..n>]

Unbilled charge estimate attributes

optional, string, max chars=40

Uniquely identifies an unbilled charge.

customer_id

optional, string, max chars=50

A unique identifier for the customer being charged.

subscription_id

optional, string, max chars=50

A unique identifier for the subscription this charge belongs to.

date_from

optional, timestamp(UTC) in seconds

Start date of this charge.

date_to

optional, timestamp(UTC) in seconds

End date of this charge.

unit_amount

optional, in cents, min=0

Unit amount of the charge item.

pricing_model

optional, enumerated string

The pricing scheme for this line item.

Enum Values

flat_fee

A fixed price that is not quantity-based.

per_unit

A fixed price per unit quantity.

tiered

There are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.

volume

The per unit price is based on the tier that the total quantity falls in.

stairstep

A quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in.

quantity

optional, integer, min=0

Quantity of the item which is represented by this charge.

amount

optional, in cents, min=0

Total amount of this charge. Typically equals to unit amount x quantity.

currency_code

required, string, max chars=3

The currency code (ISO 4217 format) for the charge.

discount_amount

optional, in cents, min=0

Total discounts for this charge.

description

optional, string, max chars=250

Detailed description about this charge.

entity_type

required, enumerated string

Specifies the modelled entity this line item is based on.

Enum Values

adhoc

Indicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case

plan_item_price

Indicates that this line item is based on plan Item Price

addon_item_price

Indicates that this line item is based on addon Item Price

charge_item_price

Indicates that this line item is based on charge Item Price

entity_id

optional, string, max chars=100

The identifier of the modelled entity this charge is based on. Will be null for 'adhoc' entity type.

is_voided

required, boolean, default=false

Will be true if the charge has been voided. Usually the unbilled charge will be voided and revised to different charges(s) during proration.

voided_at

optional, timestamp(UTC) in seconds

Timestamp indicating the date and time this charge got voided.

unit_amount_in_decimal

optional, string, max chars=39

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.

quantity_in_decimal

optional, string, max chars=33

The decimal representation of the quantity of this entity. Returned when the entity is quantity-based and multi-decimal pricing is enabled.

amount_in_decimal

optional, string, max chars=39

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.

created_at

optional, timestamp(UTC) in seconds

updated_at

required, timestamp(UTC) in seconds

Timestamp indicating when the unbilled charge was last updated

is_advance_charge

optional, boolean, default=false

The value of this parameter will be true if it is a recurring unbilled charge for a future term.

business_entity_id

optional, string, max chars=50

The unique ID of the business entity of this subscription. This is always the same as the business entity of the customer.

deleted

required, boolean

Indicates that this resource has been deleted.

tiers

The list of tiers applicable for this line item