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.
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 values are
site_default
This is the default value. The action configured for the site
at the time when the trial ends, takes effect.
The ISO 3166-2 state/province code
without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set 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
).
Note:
If you enter an invalid country code, the system will return an error.
Brexit
If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.
Action to be taken when the contract term completes.
Possible values are
renew
Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
The action_at_term_end for the new contract term is set to renew.
evergreen
Contract term completes and the subscription renews.
cancel
Contract term completes and subscription is canceled.
renew_once
Used when you want to renew the contract term just once. Does the following:-Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
The action_at_term_end for the new contract term is set to cancel.
The sum of the totals
of all the invoices raised as part of the contract term. For 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
.
It refers to the total amount of revenue that is expected to be generated from a specific contract term, calculated as the sum of all invoices raised during the term, regardless of payment status. It is based on past performance and the specified currency in the contract. If the subscription was imported, the value for total_amount_raised_before_tax
is included in the calculation of the total contract value before tax. It's important to note that this value excludes any applicable taxes.
The number of days before 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.
The number of subscription billing cycles remaining after the current one for the contract term. This attribute is only returned for active
contract terms.
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
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 values are
site_default
The action configured for the site
at the time when the trial ends, takes effect. This is the default value when trial_end_action
is not
defined for the plan.
plan_default
The action configured for the site
at the time when the trial ends, takes effect. This is the default value when trial_end_action
is defined for the plan.
activate_subscription
The subscription activates and charges are raised for non-metered items.
The ISO 3166-2 state/province code
without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set 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
).
Note:
If you enter an invalid country code, the system will return an error.
Brexit
If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.
Action to be taken when the contract term completes.
Possible values are
renew
Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
The action_at_term_end for the new contract term is set to renew.
evergreen
Contract term completes and the subscription renews.
cancel
Contract term completes and subscription is canceled.
renew_once
Used when you want to renew the contract term just once. Does the following:-Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
The action_at_term_end for the new contract term is set to cancel.
The sum of the totals
of all the invoices raised as part of the contract term. For 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
.
It refers to the total amount of revenue that is expected to be generated from a specific contract term, calculated as the sum of all invoices raised during the term, regardless of payment status. It is based on past performance and the specified currency in the contract. If the subscription was imported, the value for total_amount_raised_before_tax
is included in the calculation of the total contract value before tax. It's important to note that this value excludes any applicable taxes.
The number of days before 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.
The number of subscription billing cycles remaining after the current one for the contract term. This attribute is only returned for active
contract terms.
The deduction is due to a legacy adjustment credit applied to the invoice. The entity_id
is null
in this case. The legacy credits feature is superseded by adjustment_credit_notes
.
The type of discount that is applied to the line item. Relevant only when discounts[entity_type]
is one of item_level_discount
, item_level_coupon
, document_level_discount
, or document_level_coupon
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
.
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
Invoice estimate attributes
recurring
boolean, default=true
Whether or not the estimate for the invoice is recurring. Will be 'true' or 'false' for subscription related estimates.
The deduction is due to a legacy adjustment credit applied to the invoice. The entity_id
is null
in this case. The legacy credits feature is superseded by adjustment_credit_notes
.
The type of discount that is applied to the line item. Relevant only when discounts[entity_type]
is one of item_level_discount
, item_level_coupon
, document_level_discount
, or document_level_coupon
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
.
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.
Payment schedule estimate attributes
id
string, max chars=40
An auto-generated unique identifier for the payment schedule.
The deduction is due to a legacy adjustment credit applied to the invoice. The entity_id
is null
in this case. The legacy credits feature is superseded by adjustment_credit_notes
.
The type of discount that is applied to the line item. Relevant only when discounts[entity_type]
is one of item_level_discount
, item_level_coupon
, document_level_discount
, or document_level_coupon
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
.
Represents the preview of the credit-notes generated during 'estimate' operation. Currently applicable only for the 'Update Subscription Estimate' operation.
The deduction is due to a legacy adjustment credit applied to the invoice. The entity_id
is null
in this case. The legacy credits feature is superseded by adjustment_credit_notes
.
The type of discount that is applied to the line item. Relevant only when discounts[entity_type]
is one of item_level_discount
, item_level_coupon
, document_level_discount
, or document_level_coupon
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
.
Represents the preview of the unbilled charges generated during 'estimate' operation. Currently not applicable for the 'Subscription renewal estimate' operation.
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 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.
The price of the tier if the charge model is a stairtstep
pricing , or the price of each unit in the tier if the charge model is tiered
/volume
pricing.
The decimal representation of the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as 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.
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the 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.
The decimal representation of the quantity purchased from this tier. Returned when the line_item
is quantity-based and multi-decimal pricing
is enabled.
The decimal representation of the per-unit price for the tier when the 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.
Indicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).
flat_fee
Indicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep
pricing model, pricing_type
will be set to flat_fee
by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.
package
Indicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
Package size for the tier when pricing type is package.
Specify the number of units that make up one package. For example, if 1000 API hits are grouped into a single package, set the package size to 1000.
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
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
is used to hold the details related to payment schedules for an invoice. It will contain a list of payment_schedules
resources.
Represents the preview of the credit-notes generated during 'estimate' operation. Currently applicable only for the 'Update Subscription Estimate' operation.
Represents the preview of the unbilled charges generated during 'estimate' operation. Currently not applicable for the 'Subscription renewal estimate' operation.
Date on which the next billing happens. This will be null for non-renewing and cancelled subscriptions.
Next billing at attributes
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 values are
site_default
This is the default value. The action configured for the site
at the time when the trial ends, takes effect.
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.
Trial end action attributes
status
optional, enumerated string
The status of the subscription.
Possible values are
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.
The ISO 3166-2 state/province code
without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set 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
).
Note:
If you enter an invalid country code, the system will return an error.
Brexit
If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.
Action to be taken when the contract term completes.
Possible values are
renew
Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
The action_at_term_end for the new contract term is set to renew.
evergreen
Contract term completes and the subscription renews.
cancel
Contract term completes and subscription is canceled.
renew_once
Used when you want to renew the contract term just once. Does the following:-Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
The action_at_term_end for the new contract term is set to cancel.
The sum of the totals
of all the invoices raised as part of the contract term. For 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
.
It refers to the total amount of revenue that is expected to be generated from a specific contract term, calculated as the sum of all invoices raised during the term, regardless of payment status. It is based on past performance and the specified currency in the contract. If the subscription was imported, the value for total_amount_raised_before_tax
is included in the calculation of the total contract value before tax. It's important to note that this value excludes any applicable taxes.
The number of days before 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.
The number of subscription billing cycles remaining after the current one for the contract term. This attribute is only returned for active
contract terms.
A unique identifier for the customer this invoice belongs to
Customer id attributes
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
.
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
.
The deduction is due to a legacy adjustment credit applied to the invoice. The entity_id
is null
in this case. The legacy credits feature is superseded by adjustment_credit_notes
.
The type of discount that is applied to the line item. Relevant only when discounts[entity_type]
is one of item_level_discount
, item_level_coupon
, document_level_discount
, or document_level_coupon
Quantity of the recurring item
which is represented by this line item. For metered
line items, this value is updated from usages
once when the invoice is generated as pending
and finally when the invoice is closed
.
The decimal representation of the unit amount of the 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.
The decimal representation of the amount for the 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.
The reason due to which the line item price/amount is exempted from tax.
Possible values are
tax_not_configured
If tax is not enabled for the site
region_non_taxable
If the product sold is not taxable in this region, but it is taxable in other regions, hence this region is not part of the Taxable jurisdiction
export
You are not registered for tax in the customer's region. This is also the reason code when both billing_address
and shipping_address
have not been provided for the customer and subscription respectively
The price of the tier if the charge model is a stairtstep
pricing , or the price of each unit in the tier if the charge model is tiered
/volume
pricing.
The decimal representation of the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as 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.
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the 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.
The decimal representation of the quantity purchased from this tier. Returned when the line_item
is quantity-based and multi-decimal pricing
is enabled.
The decimal representation of the per-unit price for the tier when the 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.
Indicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).
flat_fee
Indicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep
pricing model, pricing_type
will be set to flat_fee
by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.
package
Indicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
Package size for the tier when pricing type is package.
Specify the number of units that make up one package. For example, if 1000 API hits are grouped into a single package, set the package size to 1000.
The type of deduction and the amount to which it is applied.
Possible values are
item_level_coupon
The deduction is due to a coupon applied to a line item of the invoice. The coupon id
is available as entity_id
.
document_level_coupon
The deduction is due to a coupon applied to the invoice sub_total.
The coupon id
is available as entity_id
.
promotional_credits
The deduction is due to a promotional credit
applied to the invoice. The entity_id
is null
in this case.
prorated_credits
The deduction is due to a legacy adjustment credit applied to the invoice. The entity_id
is null
in this case. The legacy credits feature is superseded by adjustment_credit_notes
.
The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed. This is applicable only for Invoice and Credit Notes API.
The ISO 3166-2 state/province code
without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set 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
).
A unique identifier for the customer this credit note belongs to
Customer id attributes
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
.
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
.
The deduction is due to a legacy adjustment credit applied to the invoice. The entity_id
is null
in this case. The legacy credits feature is superseded by adjustment_credit_notes
.
The type of discount that is applied to the line item. Relevant only when discounts[entity_type]
is one of item_level_discount
, item_level_coupon
, document_level_discount
, or document_level_coupon
Quantity of the recurring item
which is represented by this line item. For metered
line items, this value is updated from usages
once when the invoice is generated as pending
and finally when the invoice is closed
.
The decimal representation of the unit amount of the 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.
The decimal representation of the amount for the 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.
The reason due to which the line item price/amount is exempted from tax.
Possible values are
tax_not_configured
If tax is not enabled for the site
region_non_taxable
If the product sold is not taxable in this region, but it is taxable in other regions, hence this region is not part of the Taxable jurisdiction
export
You are not registered for tax in the customer's region. This is also the reason code when both billing_address
and shipping_address
have not been provided for the customer and subscription respectively
The price of the tier if the charge model is a stairtstep
pricing , or the price of each unit in the tier if the charge model is tiered
/volume
pricing.
The decimal representation of the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as 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.
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the 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.
The decimal representation of the quantity purchased from this tier. Returned when the line_item
is quantity-based and multi-decimal pricing
is enabled.
The decimal representation of the per-unit price for the tier when the 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.
Indicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).
flat_fee
Indicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep
pricing model, pricing_type
will be set to flat_fee
by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.
package
Indicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
Package size for the tier when pricing type is package.
Specify the number of units that make up one package. For example, if 1000 API hits are grouped into a single package, set the package size to 1000.
The type of deduction and the amount to which it is applied.
Possible values are
item_level_coupon
The deduction is due to a coupon applied to a line item of the invoice. The coupon id
is available as entity_id
.
document_level_coupon
The deduction is due to a coupon applied to the invoice sub_total.
The coupon id
is available as entity_id
.
promotional_credits
The deduction is due to a promotional credit
applied to the invoice. The entity_id
is null
in this case.
prorated_credits
The deduction is due to a legacy adjustment credit applied to the invoice. The entity_id
is null
in this case. The legacy credits feature is superseded by adjustment_credit_notes
.
The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed. This is applicable only for Invoice and Credit Notes API.
Timestamp indicating when the unbilled charge was last updated
Updated at attributes
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.
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.
Amount in decimal attributes
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.
The decimal representation of the quantity of this entity. Returned when the entity is quantity-based and multi-decimal pricing
is enabled.
Quantity in decimal attributes
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.
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.
Unit amount in decimal attributes
voided_at
optional, timestamp(UTC) in seconds
Timestamp indicating the date and time this charge got voided.
The price of the tier if the charge model is a stairtstep
pricing , or the price of each unit in the tier if the charge model is tiered
/volume
pricing.
The decimal representation of the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as 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.
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the 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.
The decimal representation of the quantity purchased from this tier. Returned when the line_item
is quantity-based and multi-decimal pricing
is enabled.
The decimal representation of the per-unit price for the tier when the 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.
Indicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).
flat_fee
Indicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep
pricing model, pricing_type
will be set to flat_fee
by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.
package
Indicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
Package size for the tier when pricing type is package.
Specify the number of units that make up one package. For example, if 1000 API hits are grouped into a single package, set the package size to 1000.
Generates an estimate for creating a subscription when the customer does not exist in Chargebee. This estimate API can be called when the customer has not yet signed up and you want to preview how a new subscription would look like for them.
Note:
Estimate operations do not make any changes in Chargebee; hence this API does not create an actual customer
or subscription
record.
The response contains one or more of the following objects:
subscription_estimate: The subscription details like the status of the subscription (such as in_trial or active), next billing date, and so on.
invoice_estimate:The details of the immediate invoice, if there is one. If the subscription is created in trial/future states, invoice_estimate is unavailable as no immediate invoice is generated.
next_invoice_estimate:This is returned when an immediate invoice is not generated. It contains the details of the invoice that will be generated on the next billing date of the subscription.
unbilled_charge_estimates: This contains the details of charges that have not been invoiced. This is returned only if the invoice_immediately parameter is set to false.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Override the billing alignment mode
for Calendar Billing. Only applicable when using Calendar Billing. The default value is that which has been configured for the site.
Possible values are
immediate
Subscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..
delayed
Subscription period will be aligned with the configured billing date at the next renewal.
If there are charges raised immediately for the subscription, this parameter specifies whether those charges are to be invoiced immediately or added to unbilled charges.
The default value is as per the site settings
.
Note:invoice_immediately
only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.
The document date displayed on the invoice PDF. By default, it is the date of creation of the invoice or, when Metered Billing is enabled, it can be the date of closing the invoice. Provide this value to backdate the invoice (set the invoice date to a value in the past). Backdating an invoice is done for reasons such as booking revenue for a previous date or when the non-recurring charge is effective as of a past date.
taxes
and
line_item_taxes
are computed based on the tax configuration as of this date. The date should not be more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
Computes 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.
When the purchase is made by a customer for home use
business
When the purchase is made at a place of business
senior_citizen
When the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaks
industrial
When the purchase is made by an industrial business
Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices. pass parameters as subscription_items[<param name>][<idx:0..n>]
The discount stays attached to the subscription till it is applied on an invoice once.
It is removed after that from the subscription.
forever
The discount is attached to the subscription and applied on the invoices till it is explicitly removed
.
limited_period
The discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period
and period_unit
.
Indicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).
flat_fee
Indicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep
pricing model, pricing_type
will be set to flat_fee
by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.
package
Indicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
Parameters for tax_providers_fields. Multiple tax_providers_fields can be passed by specifying unique indices. pass parameters as tax_providers_fields[<param name>][<idx:0..n>]
Generates an estimate without creating a subscription. This endpoint can be called when you want to preview details of a new subscription before actually creating one.
The following conditions must be met or tax calculation is ignored:
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
.
If there are charges raised immediately for the subscription, this parameter specifies whether those charges are to be invoiced immediately or added to unbilled charges.
The default value is as per the site settings
.
Note:invoice_immediately
only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.
Override the billing alignment mode
for Calendar Billing. Only applicable when using Calendar Billing. The default value is that which has been configured for the site.
Possible values are
immediate
Subscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..
delayed
Subscription period will be aligned with the configured billing date at the next renewal.
The document date displayed on the invoice PDF. By default, it is the date of creation of the invoice or, when Metered Billing is enabled, it can be the date of closing the invoice. Provide this value to backdate the invoice (set the invoice date to a value in the past). Backdating an invoice is done for reasons such as booking revenue for a previous date or when the non-recurring charge is effective as of a past date.
taxes
and
line_item_taxes
are computed based on the tax configuration as of this date. The date should not be more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices. pass parameters as subscription_items[<param name>][<idx:0..n>]
The discount stays attached to the subscription till it is applied on an invoice once.
It is removed after that from the subscription.
forever
The discount is attached to the subscription and applied on the invoices till it is explicitly removed
.
limited_period
The discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period
and period_unit
.
Indicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).
flat_fee
Indicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep
pricing model, pricing_type
will be set to flat_fee
by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.
package
Indicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
next_invoice_estimate:The details of the invoice to be generated later (if any) on the occasion that no immediate invoice has been generated.
credit_note_estimates:The list of credit notes (if any) generated during this operation.
unbilled_charge_estimates: The details of charges that have not been invoiced. This is returned only if the invoice_immediately parameter is set to false.
The following conditions must be met or tax calculation is ignored:
When change_option
is set to specific_date
, then set the date/time at which the subscription change is to happen or has happened. Note:
It is recommended not to pass this parameter along with reactivate_from.
changes_scheduled_at
can be set to a value in the past. This is called backdating the subscription change and is performed when the subscription change has already been provisioned but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:
Backdating must be enabled for subscription change operations.
Only the following changes can be backdated:
Changes in the recurring items or their prices.
Addition of non-recurring items.
Subscription status is active, cancelled, or non_renewing.
The current day of the month does not exceed the limit set in Chargebee for backdating subscription change. This limit is typically the day of the month by which the accounting for the previous month must be closed.
The date is on or after current_term_start.
The date is on or after the last date/time any of the following changes were made:
Changes in the recurring items or their prices.
Addition of non-recurring items.
The date is not more than duration X into the past where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April, changes_scheduled_at cannot be earlier than 14th February.
.
If true
then the existing subscription_items
list for the subscription is replaced by the one provided. If false
then the provided subscription_items
list gets added to the existing list.
The document date displayed on the invoice PDF. The default value is the current date. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date. Moreover, if create_pending_invoices
is set to true
, and if the site is configured to set invoice dates to date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes and line_item_taxes are computed based on the tax configuration as of invoice_date.
When passing this parameter, the following prerequisites must be met:
invoice_date must be in the past.
invoice_date is not more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
It is not earlier than changes_scheduled_at, reactivate_from, or trial_end.
The number of subscription billing cycles to invoice in advance.
If a new term is started for the subscription due to this API call, then 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.
If the subscription status
is cancelled
and it is being reactivated via this operation, this is the date/time at which the subscription should be reactivated.
Note:
It is recommended not to pass this parameter along with changed_scheduled_at.
reactivate_from
can be backdated (set to a value in the past). Use backdating when the subscription has been reactivated already but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:
Backdating must be enabled for subscription reactivation operations.
The current day of the month does not exceed the limit set in Chargebee for backdating subscription change. This limit is the day of the month by which the accounting for the previous month must be closed.
The date is on or after the last date/time any of the product catalog items of the subscription were changed.
The date is not more than duration X into the past where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April, changes_scheduled_at cannot be earlier than 14th February.
.
If 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
.
Say the subscription has the renewal date as 28th of every month. When the plan-item price of the subscription is set to one that has the same billing period as the current plan-item price, the subscription change does not change the term. In other words, the subscription still renews on the 28th. Passing this parameter as true
will have the subscription reset its term to the current date (provided end_of_term
is false).
Note:
When the new plan-item price has a billing period different from the current plan-item price of the subscription, the term is always reset, regardless of the value passed for this parameter.
Applicable only for 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.
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
.
If there are charges raised immediately for the subscription, this parameter specifies whether those charges are to be invoiced immediately or added to unbilled charges.
The default value is as per the site settings
.
Note:invoice_immediately
only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.
Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices. pass parameters as subscription_items[<param name>][<idx:0..n>]
The discount stays attached to the subscription till it is applied on an invoice once.
It is removed after that from the subscription.
forever
The discount is attached to the subscription and applied on the invoices till it is explicitly removed
.
limited_period
The discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period
and period_unit
.
The discount (given by discounts[id]
) is removed from the subscription. Subsequent invoices will no longer have the discount applied. Tip:
If you want to replace a discount, remove
it and add
another in the same API call.
Indicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).
flat_fee
Indicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep
pricing model, pricing_type
will be set to flat_fee
by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.
package
Indicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
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,
estimate.subscription_estimate has the current subscription details like its status, next billing date, and so on.
estimate.invoice_estimate
has details of the invoice that will be generated at the next billing date.
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:
This API will not generate a renewal invoice if an advance invoice is already present for the subscription.
For 'Non Renewing' subscriptions, only the delayed charges will be included in the invoice estimate.
This API is not supported for 'Cancelled' subscriptions.
Only the subscription's charges will be included. If you have enabled the Consolidated invoicing feature, use the Upcoming Invoices estimate available for the Customer object to get the actual estimate invoice for the customer.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
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
.
This API is used to generate an invoice estimate for preview. Estimate details include the number of billing cycles to be invoiced in advance, the number of billing cycles in one interval, advance invoicing schedules, and so on.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
For 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.
For 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.
.
Parameters for specific_dates_schedule. Multiple specific_dates_schedule can be passed by specifying unique indices. pass parameters as specific_dates_schedule[<param name>][<idx:0..n>]
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:
An invoice exists for the current term and its status is not voided.
Returns an estimate object with one of the following components depending on the value of invoice_immediately.
If the value is true: an invoice_estimate object that corresponds to the regenerated invoice.
If the value is false: a list of unbilled_charge_estimate objects corresponding to all the unbilled charges created for the current term of the subscription.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Only applicable when Consolidated Invoicing
is enabled for the customer. Set 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:
estimate.invoice_estimates[] has details of the invoices scheduled to be generated.
Note: If consolidated invoicing is enabled you may use this API to test whether upcoming renewals are consolidated.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
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,
estimate.subscription_estimate has the subscription details like the status of the subscription (in_trial, active, etc.), next billing date, and so on.
estimate.invoice_estimate has details of the invoice that will be generated immediately. This will not be present if no immediate invoice is generated for this operation. This will happen when
prorate parameter is false, or
invoice_immediately parameter is false, or
subscription is in in-trial state
estimate.credit_note_estimates[] has details of the credit-notes that will get generated during this operation. This list will be empty if no credit-note gets generated during this operation.
estimate.unbilled_charge_estimates[] has details of the unbilled charges. This is returned only if invoice_immediately is set as false.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
If there are charges raised immediately for the subscription, this parameter specifies whether those charges are to be invoiced immediately or added to unbilled charges.
The default value is as per the site settings
.
Note:invoice_immediately
only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.
If the subscription does not have a contract term:
Determines when to cancel the subscription.
If the subscription has a contract term:
This parameter is not applicable.
Possible values are
immediately
This is used to cancel the subscription with immediate effect
end_of_term
This is used to cancel a subscription at the end of the current billing cycle
specific_date
This is used to cancel a subscription on a specified date. The change occurs as of the date/time defined in cancel_at
end_of_billing_term
This is used to cancel a subscription either at the end of the advance term, if it's billed for future renewals or at the end of its current billing cycle
(Deprecated) Use cancel_option instead.
Applicable only when the subscription does not have contract terms.
Set this to true if you want to cancel the subscription at the end of the current subscription billing cycle. The subscription status changes to non_renewing.
The date is on or after the most recent change involving:
Addition/change/removal of plan or addon item prices.
Addition of charge item prices.
The date is not more than one billing period into the past. For example, if the plan's billing period is two months and today is April 14, cancel_at cannot be earlier than February 14.
If the subscription does not have a contract term:
Specifies how to handle credits for current term charges when canceling immediately (i.e., cancel_option is immediately). If not specified, the site-level setting is used.
If the subscription has a contract term:
Specifies how to handle credits for current term charges when contract_term_cancel_option is terminate_immediately. If not specified, the site-level setting is used.
Possible values are
none
No credits notes are created.
prorate
Prorated credits are issued.
full
Credits are issues for the full value of the current term charges.
If the subscription does not have a contract term:
Specifies how to handle unbilled charges when canceling immediately (i.e., cancel_option is immediately). If not specified, the site-level setting is used.
If the subscription has a contract term:
Specifies how to handle unbilled charges when contract_term_cancel_option is terminate_immediately. If not specified, the site-level setting is used.
Possible values are
invoice
An invoice is generated immediately with the unbilled charges.
If the subscription does not have a contract term:
Specifies how to handle past due invoices when canceling immediately (i.e., cancel_option is immediately). If not specified, the site-level setting is used.
If the subscription has a contract term:
Specifies how to handle past due invoices when contract_term_cancel_option is terminate_immediately. If not specified, the site-level setting is used.
Possible values are
no_action
No action is taken.
schedule_payment_collection
Applies excess payments and refundable credits to past due invoices. If any amount remains and auto_collection
is on
, the remaining amount is automatically charged to the available payment method.
write_off
Applies excess payments and refundable credits to past due invoices. Any remaining balance is written off. Note: The credit note for the write-off is not included in the API response.
If the subscription does not have a contract term:
Specifies how to handle refundable credits when canceling immediately (i.e., cancel_option is immediately). If not specified, the site-level setting is used.
If the subscription has a contract term:
Specifies how to handle refundable credits when contract_term_cancel_option is terminate_immediately. If not specified, the site-level setting is used.
Possible values are
no_action
No action is taken.
schedule_refund
Refunds remaining credits after applying them to any past due invoices.
Required when the subscription has a contract term. Determines when to cancel the subscription along with the contract term.
Possible values are
terminate_immediately
Cancels the subscription and contract term immediately. Sets the contract term's status to terminated and collects any termination fee, if applicable.
To specify the termination fee, include a single object in the subscription_items array. If not specified, the default termination fee is applied (if configured).
end_of_contract_term
Prevents the contract term from renewing and schedules the subscription for cancellation at the end of the contract term.
specific_date
Cancels the subscription and contract term on the date specified by cancel_at. Sets action_at_term_end to cancel. Note: Contact Chargebee Support to enable this option for your Chargebee site.
end_of_subscription_billing_term
Cancels the subscription and contract term at the end of the current billing cycle. Sets action_at_term_end to cancel. Note: Contact Chargebee Support to enable this option for your Chargebee site.
The document date displayed on the invoice PDF. The default value is the current date. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date. Moreover, if create_pending_invoices
is true
, and if the site is configured to set invoice dates to date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes
and line_item_taxes
are computed based on the tax
configuration as of invoice_date.
When passing this parameter, the following prerequisites must be met:
invoice_date must be in the past.
invoice_date is not more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
Reason code for canceling the subscription. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Subscriptions > Subscription Cancellation.
Must be passed if set as mandatory in the app. The codes are case-sensitive.
Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices. pass parameters as subscription_items[<param name>][<idx:0..n>]
This API provides an estimate of the details pertaining to the pause_subscription operation. It returns attributes such as pause_date and resume_date. This is similar to the Pause a subscription API with the exception that the subscription is not paused. Only an estimate for this operation is created.
In the response,
estimate.subscription_estimate has the subscription details.
estimate.invoice_estimate has details of the invoice that are generated immediately. This is not present if no immediate invoices are generated for this operation.
estimate.credit_note_estimates[] has details of the credit notes that are generated during this operation. This list is empty if no credit notes are generated.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Applicable when unbilled charges are present for the subscription and pause_option is set as immediately. Note: On the invoice raised, an automatic charge is attempted on the payment method available, if customer's auto-collection property is set to on.
Possible values are
no_action
Retain as unbilled
If no_action is chosen, charges are added to the resumption invoice.
invoice
Invoice charges
If invoice is chosen, an automatic charge is attempted on the payment method available if the customer has enabled auto-collection. If a payment collection fails or when auto-collection is not enabled, the invoice is closed as unpaid.
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,
estimate.subscription_estimate has the subscription details.
estimate.invoice_estimate
has details of the invoice that will be generated immediately. This will not be present if no immediate invoice is generated for this operation. This will happen for in-term resumption++
.
++What is an "in-term resumption"?
An "in-term resumption" is when the resumption happens within the billing term of the subscription.
estimate.next_invoice_estimate
has details of the invoice that will be generated during the next billing date of this subscription. This will be present only if no immediate invoice is generated during this operation (scenario mentioned above) and this subscription has next billing.
The generated invoice_estimate/next_invoice_estimate will include all the balances - Promotional Credits
, Refundable Credits, and Excess Payments - if any.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Applicable when charges get added during this operation and resume_option
is set as 'immediately'. Allows to raise invoice immediately or add them to unbilled charges.
This endpoint generates an estimate for a subscription that is intended to be a gift. The estimate provides details about the gift sender, gift recipient, address details of the recipient, and the type and details of subscription items included in the gift.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices. pass parameters as subscription_items[<param name>][<idx:0..n>]
The document date displayed on the invoice PDF. By default, it is the date of creation of the invoice or, when Metered Billing is enabled, it can be the date of closing the invoice. Provide this value to backdate the invoice (set the invoice date to a value in the past). Backdating an invoice is done for reasons such as booking revenue for a previous date or when the non-recurring charge is effective as of a past date.
taxes
and
line_item_taxes
are computed based on the tax configuration as of this date. The date should not be more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
Indicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).
flat_fee
Indicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep
pricing model, pricing_type
will be set to flat_fee
by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.
package
Indicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
Parameters for notes_to_remove. Multiple notes_to_remove can be passed by specifying unique indices. pass parameters as notes_to_remove[<param name>][<idx:0..n>]
notes_to_remove[entity_type][0..n]
optional, enumerated string
Possible values are
customer
Entity that represents a customer.
subscription
Entity that represents a subscription of customer.
coupon
Entity that represents a coupon.
plan_item_price
Indicates that this line item is based on plan Item Price
Parameters for tax_providers_fields. Multiple tax_providers_fields can be passed by specifying unique indices. pass parameters as tax_providers_fields[<param name>][<idx:0..n>]
Generates an estimate without creating a payment schedule. This endpoint can be called when you want to preview details of a new payment schedule before actually creating one.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
The unique identifier for the payment_schedule_scheme.
This identifier is used to retrieve the payment schedule scheme, which is then applied to calculate the amount and date for the specified number of payment schedules.
Defines the payment schedule amount set for an invoice. If this is not provided, the total invoice.amount_due
is used. This value is mandatory in case invoice_id
is not provided.
The date from which the payment schedule will start. This is applicable only when invoice_id is not provided. If invoice_id
is provided, we will consider invoice.due_date
.
Settings
Configure SDK
