ChargebeeAPI

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

Object of parameters for subscription_estimate

subscription_estimates

Array containing object of parameters for subscription_estimates

invoice_estimate

Object of parameters for invoice_estimate

invoice_estimates

Array containing object of parameters for invoice_estimates

payment_schedule_estimates

Array containing object of parameters for payment_schedule_estimates

next_invoice_estimate

Object of parameters for next_invoice_estimate

credit_note_estimates

Array containing object of parameters for credit_note_estimates

unbilled_charge_estimates

Array containing object of parameters for unbilled_charge_estimates

Subscription estimate attributes

id
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.

Possible 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.

Possible 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

Object of parameters for shipping_address

contract_term

Object of parameters for contract_term

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.

Possible 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

Array containing object of parameters for discounts

taxes

Array containing object of parameters for taxes

GROUPED:line_items|line_item_tiers|line_item_discounts|line_item_taxes|line_item_credits|line_item_addresses
line_items

Array containing object of parameters for line_items

line_item_tiers

Array containing object of parameters for line_item_tiers

line_item_discounts

Array containing object of parameters for line_item_discounts

line_item_taxes

Array containing object of parameters for line_item_taxes

line_item_credits

Array containing object of parameters for line_item_credits

line_item_addresses

Array containing object of parameters for line_item_addresses

Payment schedule estimate attributes

id
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.

Possible 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

Array containing object of parameters for 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.

Possible 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.

Possible 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

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 credit note belongs to

discounts

Array containing object of parameters for discounts

taxes

Array containing object of parameters for taxes

GROUPED:line_items|line_item_tiers|line_item_discounts|line_item_taxes
line_items

Array containing object of parameters for line_items

line_item_tiers

Array containing object of parameters for line_item_tiers

line_item_discounts

Array containing object of parameters for line_item_discounts

line_item_taxes

Array containing object of parameters for line_item_taxes

Unbilled charge estimate attributes

id
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.

Possible 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.

entity_type
required, enumerated string

Specifies the modelled entity this line item is based on.

Possible 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.

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

Array containing object of parameters for tiers