A quote is an estimate of the invoice with the charges likely to occur when customers buy an item. A quote can be converted to a regular invoice once the customer accepts it.

Sample quote [ JSON ]

{ "id": "2", "customer_id": "8avVGOkx8U1MX", "status": "open", "operation_type": "onetime_invoice", "price_type": "tax_exclusive", "valid_till": 1540883887, "date": 1540797487, "sub_total": 1400, "total": 1400, "credits_applied": 0, "amount_paid": 0, "amount_due": 1400, "updated_at": 1540797488, "resource_version": 1540797488087, "object": "quote", "line_items": [ { "id": "li_XpbGBzkR7qfEcQ2", "date_from": 1540797486, "date_to": 1540797486, "unit_amount": 200, "quantity": 2, "amount": 400, "pricing_model": "per_unit", "is_taxed": false, "tax_amount": 0, "object": "line_item", "description": "Day Pass", "entity_type": "addon", "entity_id": "day-pass", "discount_amount": 0, "item_level_discount_amount": 0 }, {..} ], "line_item_discounts": [], "taxes": [], "line_item_taxes": [], "currency_code": "USD" }

API Index URL GET

https://{site}.chargebee.com/api/v2/quotes
id
The quote number. Acts as a identifier for quote and typically generated sequentially.
string, max chars=50
po_number
Purchase Order Number.
optional, string, max chars=100
customer_id
The identifier of the customer this quote belongs to.
string, max chars=50
subscription_id
The identifier of the subscription this quote belongs to.
optional, string, max chars=50
status
Current status of this quote.
enumerated string
Possible values are
openOpen.acceptedAccepted.declinedDeclined.invoicedInvoiced.closedClosed.
operation_type
Operation Type.
enumerated string
Possible values are
create_subscription_for_customercreate_subscription_for_customer.change_subscriptionchange_subscription.onetime_invoiceonetime_invoice.
vat_number
VAT/ Tax registration number of the customer. Learn more.
optional, string, max chars=20
price_type
The price type of the quote.
enumerated string, default=tax_exclusive
Possible values are
tax_exclusiveAll amounts in the document are exclusive of tax.tax_inclusiveAll amounts in the document are inclusive of tax.
valid_till
Quote will be valid till this date. After this date quote will be marked as closed.
timestamp(UTC) in seconds
date
Creation date of the quote. Typically this is the date on which quote is generated.
timestamp(UTC) in seconds
sub_total
Sub-total in cents.
in cents, min=0
total
Total in cents.
optional, in cents, default=0, min=0
credits_applied
Credits applied to this quote in cents.
optional, in cents, default=0, min=0
amount_paid
Existing outstanding payments if any, applied to this quote in cents.
optional, in cents, default=0, min=0
amount_due
Amount due in cents.
optional, in cents, default=0, min=0
resource_version
Version number of this resource. Each update of this resource results in incremental change of this number. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long
updated_at
Timestamp indicating when this quote was last updated.
optional, timestamp(UTC) in seconds
currency_code
The currency code (ISO 4217 format) of the quote.
string, max chars=3
line_items
Show attributes[+]
The list of items in this quote.
optional, list of line_item
Line item attributes
id
Uniquely identifies a line_item.
optional, string, max chars=40
subscription_id
A unique identifier for the subscription this lineitem belongs to.
optional, string, max chars=3
date_from
Start date of this lineitem.
timestamp(UTC) in seconds
date_to
End date of this lineitem.
timestamp(UTC) in seconds
unit_amount
Unit amount of the lineitem.
in cents
quantity
Quantity of the recurring item which is represented by this lineitem.
optional, integer, default=1
amount
Total amount of this lineitem. Typically equals to unit amount x quantity.
optional, in cents
pricing_model
Charges a single price for the plan/addon.
optional, enumerated string
Possible values are
flat_feeCharge a single price on recurring basis.per_unitCharge the price for each unit of the plan for the subscription on recurring basis.tieredCharges a different per unit price for the quantity purchased from every tier.volumeCharges the per unit price for the total quantity purchased based on the tier under which it falls.stairstepCharges a price for a range.
is_taxed
Specifies whether this line item is taxed or not.
boolean, default=false
tax_amount
The tax amount charged for this item.
optional, in cents, default=0, min=0
tax_rate
Rate of tax used to calculate tax for this lineitem.
optional, double, min=0.0, max=100.0
discount_amount
Total discounts for this line.
optional, in cents, min=0
item_level_discount_amount
'Item' level discounts for this line.
optional, in cents, min=0
description
Detailed description about this lineitem.
string, max chars=250
entity_type
Specifies the modelled entity (plan / addon etc) this lineitem is based on.
enumerated string
Possible values are
plan_setupIndicates that this lineitem is based on 'Plan Setup' charge. The 'entity_id' attribute specifies the plan id.planIndicates that this lineitem is based on 'Plan' entity. The 'entity_id' attribute specifies the plan id.addonIndicates that this lineitem is based on 'Addon' entity. The 'entity_id' attribute specifies the addon id.adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case.
tax_exempt_reason
The reason or category due to which the line item price/amount is excluded from taxable amount.
optional, enumerated string
Possible values are
tax_not_configuredIf tax is not enabled for the site.region_non_taxableIf 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.exportIf the Merchant is not registered for Tax in this region, taxes will not be applied.customer_exemptIf the Customer is marked as Tax exempt.product_exemptIf the Plan or Addon is marked as Tax exempt.zero_ratedIf the rate of tax is 0% and no Sales/ GST tax is collectable for that line item.reverse_chargeIf the Customer is identified as B2B customer (when VAT Number is entered), applicable for EU only.high_value_physical_goodsIf physical goods are sold from outside Australia to customers in Australia, and the price of all the physical good line items is greater than AUD 1000, then tax will not be applied.
entity_id
The identifier of the modelled entity this lineitem is based on. Will be null for 'adhoc' entity type.
optional, string, max chars=100
discounts
Show attributes[+]
The list of discounts applied to this quote.
optional, list of discount
Discount attributes
amount
Discount amount.
in cents, min=0
description
Detailed description of this discount line item.
optional, string, max chars=250
entity_type
Type of this Discount lineitem.
enumerated string
Possible values are
item_level_couponRepresents the 'Item' level coupons applied to this invoice. Further the 'entity_id' attribute specifies the coupon id this discount is based on.document_level_couponRepresents the 'Document' level coupons applied to this document. Further the 'entity_id' attribute specifies the coupon id this discount is based on.promotional_creditsRepresents the Promotional Credits item in invoice. The 'entity_id' attribute will be null in this case.prorated_creditsRepresents the credit adjustment items in invoice. The 'entity_id' attribute will be null in this case.
entity_id
The identifier of the modelled entity this lineitem is bases on. Will be null for 'Prorated Credits' & 'Promotional Credits'.
optional, string, max chars=100
line_item_discounts
Show attributes[+]
The list of discount(s) applied for each line item of this quote.
optional, list of line_item_discount
Line item discount attributes
line_item_id
The unique reference id of the line item for which the discount is applicable.
string, max chars=50
discount_type
Type of this discount line item.
enumerated string
Possible values are
item_level_couponRepresents the 'Item' level coupons applied to this invoice. Further the 'coupon_id' attribute specifies the coupon id this discount is based on.document_level_couponRepresents the 'Document' level coupons applied to this document. Further the 'coupon_id' attribute specifies the coupon id this discount is based on.promotional_creditsRepresents the Promotional Credits item in invoice. The 'coupon_id' attribute will be null in this case.prorated_creditsRepresents the credit adjustment items in invoice. The 'coupon_id' attribute will be null in this case.
coupon_id
Coupon id.
optional, string, max chars=50
discount_amount
Discount amount.
in cents, min=0
The list of taxes applied to this quote.
optional, list of tax
Tax attributes
name
The name of the tax applied. E.g. GST.
string, max chars=100
amount
The tax amount.
in cents, min=0
description
Description of the tax item.
optional, string, max chars=250
line_item_taxes
Show attributes[+]
The list of taxes applied on line items.
optional, list of line_item_tax
Line item tax attributes
line_item_id
The unique reference id of the line item for which the tax is applicable.
optional, string, max chars=40
tax_name
The name of the tax applied.
string, max chars=100
tax_rate
The rate of tax used to calculate tax amount.
double, default=0.0, min=0.0, max=100.0
tax_amount
The tax amount.
in cents, min=0
tax_juris_type
The type of tax jurisdiction.
optional, enumerated string
Possible values are
countryThe tax jurisdiction is a country.stateThe tax jurisdiction is a state.countyThe tax jurisdiction is a county.cityThe tax jurisdiction is a city.specialSpecial tax jurisdiction.otherJurisdictions other than the ones listed above.
tax_juris_name
The name of the tax jurisdiction.
optional, string, max chars=250
tax_juris_code
The tax jurisdiction code.
optional, string, max chars=250
shipping_address
Show attributes[+]
Shipping address for the quote.
optional, shipping_address
Shipping addres attributes
first_name
First name.
optional, string, max chars=150
last_name
Last name.
optional, string, max chars=150
email
Email.
optional, string, max chars=70
company
Company name.
optional, string, max chars=250
phone
Phone number.
optional, string, max chars=50
line1
Address line 1.
optional, string, max chars=180
line2
Address line 2.
optional, string, max chars=150
line3
Address line 3.
optional, string, max chars=150
city
City.
optional, string, max chars=50
state_code
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
state
The state/province name.
optional, string, max chars=50
country
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
zip
Zip or Postal code.
optional, string, max chars=20
validation_status
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
billing_address
Show attributes[+]
Billing address for the quote.
optional, billing_address
Billing addres attributes
first_name
First name.
optional, string, max chars=150
last_name
Last name.
optional, string, max chars=150
email
Email.
optional, string, max chars=70
company
Company name.
optional, string, max chars=250
phone
Phone number.
optional, string, max chars=50
line1
Address line 1.
optional, string, max chars=150
line2
Address line 2.
optional, string, max chars=150
line3
Address line 3.
optional, string, max chars=150
city
City.
optional, string, max chars=50
state_code
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
state
State or Province.
optional, string, max chars=50
country
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
zip
Zip or Postal code.
optional, string, max chars=20
validation_status
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
Retrieves the quotes identified by the 'number' specified in the url.
Sample Request
curl  https://{site}.chargebee.com/api/v2/quotes/2 \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/quotes/2 \
     -u {site_api_key}:

Sample Response [ JSON ]

{"quote": { "id": "quote001", "customer_id": "5SK0b54PR6F9LLE8g", "status": "invoiced", "operation_type": "onetime_invoice", "price_type": "tax_exclusive", "valid_till": 1540883887, "date": 1540797487, "sub_total": 1400, "total": 1400, "credits_applied": 0, "amount_paid": 0, "amount_due": 1400, "updated_at": 1540797488, "resource_version": 1540797488087, "object": "quote", "line_items": [ { "id": "li_XpbGBzkR7qfEcQ2", "date_from": 1540797486, "date_to": 1540797486, "unit_amount": 200, "quantity": 2, "amount": 400, "pricing_model": "per_unit", "is_taxed": false, "tax_amount": 0, "object": "line_item", "description": "Day Pass", "entity_type": "addon", "entity_id": "day-pass", "discount_amount": 0, "item_level_discount_amount": 0 }, {..} ], "line_item_discounts": [], "taxes": [], "line_item_taxes": [], "currency_code": "USD" }}

URL Format GET

https://{site}.chargebee.com/api/v2/quotes/{quote_id}
Resource object representing quote.
always returned

Sample admin console URL

https://{site}.chargebee.com/admin-console/quotes/2
Sample Request
curl  https://{site}.chargebee.com/api/v2/customers/4gkYnd21ouvW/create_subscription_quote \
     -u {site_api_key}: \
     -d subscription[plan_id]="basic"
copy
curl  https://{site}.chargebee.com/api/v2/customers/4gkYnd21ouvW/create_subscription_quote \
     -u {site_api_key}: \
     -d subscription[plan_id]="basic"

Sample Response [ JSON ]

{"quote": { "id": "6", "customer_id": "future_billing", "status": "open", "operation_type": "create_subscription_for_customer", "price_type": "tax_exclusive", "valid_till": 1543927771, "date": 1543841371, "sub_total": 1395, "total": 1395, "credits_applied": 0, "amount_paid": 0, "amount_due": 1395, "updated_at": 1543841371, "resource_version": 1543841371788, "object": "quote", "line_items": [ { "id": "li_XpbGC2fRBAf3th7", "date_from": 1546519771, "date_to": 1549198171, "unit_amount": 900, "quantity": 1, "amount": 900, "pricing_model": "per_unit", "is_taxed": false, "tax_amount": 0, "object": "line_item", "description": "Basic", "entity_type": "plan", "entity_id": "basic", "discount_amount": 0, "item_level_discount_amount": 0 }, {..} ], "line_item_discounts": [], "taxes": [], "line_item_taxes": [], "currency_code": "USD" }}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer_id}/create_subscription_quote
billing_cycles
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
terms_to_charge
The number of future renewals for which advance invoicing is done. However, if a new term gets started in this operation, the specified terms_to_charge will be inclusive of this new term.
optional, integer, min=1
billing_alignment_mode
Applicable when calendar billing is enabled and subscription is getting created in active / non_renewing states. Unless specified the configured default value will be used.
optional, enumerated string
Possible values are
immediateSubscription period will be aligned with the configured billing date immediately.delayedSubscription period will be aligned with the configured billing date at a later date (subsequent renewals).
mandatory_addons_to_remove[0..n]
List of addons IDs that are mandatory to the plan and has to be removed from the subscription.
optional, list of string
coupon_ids[0..n]
Identifier of the coupon as a List. Coupon Codes can also be passed.
optional, list of string
subscription
Parameters for subscription
pass parameters as subscription[<param name>]
subscription[id]
A unique identifier to identify the subscription. You will use this to perform all operations on this subscription.
optional, string, max chars=50
subscription[plan_id]
Identifier of the plan for this subscription.
required, string, max chars=100
subscription[plan_quantity]
Plan quantity for this subscription.
optional, integer, default=1, min=1
subscription[plan_unit_price]
Amount that will override the Plan's default price.
optional, in cents, min=0
subscription[setup_fee]
Amount that will override the default setup fee.
optional, in cents, min=0
subscription[start_date]
Allows you to specify a future date or a past date on which the subscription starts.Past dates can be entered in case the subscription has already started. Any past date entered must be within the current billing cycle/plan term. The subscription will start immediately if this parameter is not passed.
optional, timestamp(UTC) in seconds
subscription[trial_end]
The time at which the trial ends for this subscription. Can be specified to override the default trial period.If '0' is passed, the subscription will be activated immediately.
optional, timestamp(UTC) in seconds
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
First name.
optional, string, max chars=150
shipping_address[last_name]
Last name.
optional, string, max chars=150
shipping_address[email]
Email.
optional, string, max chars=70
shipping_address[company]
Company name.
optional, string, max chars=250
shipping_address[phone]
Phone number.
optional, string, max chars=50
shipping_address[line1]
Address line 1.
optional, string, max chars=180
shipping_address[line2]
Address line 2.
optional, string, max chars=150
shipping_address[line3]
Address line 3.
optional, string, max chars=150
shipping_address[city]
City.
optional, string, max chars=50
shipping_address[state_code]
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
shipping_address[state]
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
shipping_address[zip]
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
shipping_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
addons[id][0..n]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
addons[quantity][0..n]
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1
addons[unit_price][0..n]
Amount that will override the Addon's default price. The Plan's billing frequency will not be considered for overriding. E.g. If the Plan's billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).
optional, in cents, min=0
addons[billing_cycles][0..n]
Number of billing cycles the addon will be charged for.
optional, integer, min=1
addons[trial_end][0..n]
The time at which the trial ends for the addon. In order to use this param please contact support@chargebee.com.
optional, timestamp(UTC) in seconds
event_based_addons
Parameters for event_based_addons. Multiple event_based_addons can be passed by specifying unique indices.
pass parameters as event_based_addons[<param name>][<idx:0..n>]
event_based_addons[id][0..n]
A unique 'id' used to identify the addon.
optional, string, max chars=100
event_based_addons[quantity][0..n]
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1
event_based_addons[unit_price][0..n]
Amount that will override the Addon's default price.
optional, in cents, min=0
event_based_addons[on_event][0..n]
Event on which this addon will be charged.
optional, enumerated string
Possible values are
subscription_creationAddon will be charged on subscription creation.subscription_trial_startAddon will be charged when the trial period starts.plan_activationAddon will be charged on plan activation.subscription_activationAddon will be charged on subscription activation.
event_based_addons[charge_once][0..n]
If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean, default=true
event_based_addons[charge_on][0..n]
Indicates when the non-recurring addon will be charged.
optional, enumerated string
Possible values are
immediatelyCharges for the addon will be applied immediately.on_eventCharge for the addon will be applied on the occurrence of a specified event.
Resource object representing quote.
always returned
Sample Request
curl  https://{site}.chargebee.com/api/v2/quotes/update_subscription_quote \
     -u {site_api_key}: \
     -d subscription[id]="8avVGOkx8U1MX" \
     -d subscription[plan_id]="basic" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"
copy
curl  https://{site}.chargebee.com/api/v2/quotes/update_subscription_quote \
     -u {site_api_key}: \
     -d subscription[id]="8avVGOkx8U1MX" \
     -d subscription[plan_id]="basic" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

Sample Response [ JSON ]

{"quote": { "id": "7", "customer_id": "future_billing", "subscription_id": "future_billing", "status": "open", "operation_type": "change_subscription", "price_type": "tax_exclusive", "valid_till": 1543927886, "date": 1543841486, "sub_total": 1395, "total": 1395, "credits_applied": 0, "amount_paid": 0, "amount_due": 1395, "updated_at": 1543841486, "resource_version": 1543841486117, "object": "quote", "line_items": [ { "id": "li_XpbGC2fRBAfXdiB", "date_from": 1546918958, "date_to": 1549597358, "unit_amount": 900, "quantity": 1, "amount": 900, "pricing_model": "per_unit", "is_taxed": false, "tax_amount": 0, "object": "line_item", "subscription_id": "future_billing", "description": "Basic", "entity_type": "plan", "entity_id": "basic", "discount_amount": 0, "item_level_discount_amount": 0 }, {..} ], "line_item_discounts": [], "taxes": [], "line_item_taxes": [], "currency_code": "USD" }}

URL Format POST

https://{site}.chargebee.com/api/v2/quotes/update_subscription_quote
billing_cycles
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
replace_addon_list
Should be true if the existing addons should be replaced with the ones that are being passed.
optional, boolean, default=false
mandatory_addons_to_remove[0..n]
List of addons IDs that are mandatory to the plan and has to be removed from the subscription.
optional, list of string
terms_to_charge
The number of future renewals for which advance invoicing is done. However, if a new term gets started in this operation, the specified terms_to_charge will be inclusive of this new term.
optional, integer, min=1
reactivate_from
The time from which this subscription should be reactivated.
optional, timestamp(UTC) in seconds
billing_alignment_mode
Applicable when calendar billing is enabled and a new term gets started during this operation. Unless specified the configured default value will be used.
optional, enumerated string
Possible values are
immediateSubscription period will be aligned with the configured billing date immediately.delayedSubscription period will be aligned with the configured billing date at a later date (subsequent renewals).
coupon_ids[0..n]
Identifier of the coupon as a List. Coupon Codes can also be passed.
optional, list of string
replace_coupon_list
Should be true if the existing coupons should be replaced with the ones that are being passed.
optional, boolean, default=false
force_term_reset
Applicable for 'Active' & 'Non Renewing' states alone. Generally, subscription's term will be reset (i.e current term is ended and a new term starts immediately) when a new plan having different billing frequency is specified in the input. For all the other cases, the subscription's term will remain intact. Now for this later scenario, if you want to force a term reset you can specify this param as 'true'.
Note: Specifying this value as 'false' has no impact on the default behaviour.
optional, boolean, default=false
reactivate
Applicable only for cancelled subscriptions. Once this is passed as true, cancelled subscription will become active; otherwise subscription changes will be made but the the subscription state will remain cancelled. If not passed, subscription will be activated only if there is any change in subscription data.
optional, boolean
subscription
Parameters for subscription
pass parameters as subscription[<param name>]
subscription[id]
A unique identifier to identify the subscription. You will use this to perform all operations on this subscription.
required, string, max chars=50
subscription[plan_id]
Identifier of the plan for this subscription.
optional, string, max chars=100
subscription[plan_quantity]
Represents the plan quantity for this subscription.
optional, integer, default=1, min=1
subscription[plan_unit_price]
Amount that will override the Plan's default price.
optional, in cents, min=0
subscription[setup_fee]
Amount that will override the default setup fee.
optional, in cents, min=0
subscription[start_date]
Applicable only for 'future' subscriptions. The new start date of the 'future' subscription.
optional, timestamp(UTC) in seconds
subscription[trial_end]
The time at which the trial should end for this subscription. Can be specified to override the default trial period defined in plan. If '0' is passed, the subscription will be activated immediately.
optional, timestamp(UTC) in seconds
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
First name.
optional, string, max chars=150
billing_address[last_name]
Last name.
optional, string, max chars=150
billing_address[email]
Email.
optional, string, max chars=70
billing_address[company]
Company name.
optional, string, max chars=250
billing_address[phone]
Phone number.
optional, string, max chars=50
billing_address[line1]
Address line 1.
optional, string, max chars=150
billing_address[line2]
Address line 2.
optional, string, max chars=150
billing_address[line3]
Address line 3.
optional, string, max chars=150
billing_address[city]
City.
optional, string, max chars=50
billing_address[state_code]
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
billing_address[state]
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
billing_address[zip]
Zip or Postal code.
optional, string, max chars=20
billing_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
billing_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
First name.
optional, string, max chars=150
shipping_address[last_name]
Last name.
optional, string, max chars=150
shipping_address[email]
Email.
optional, string, max chars=70
shipping_address[company]
Company name.
optional, string, max chars=250
shipping_address[phone]
Phone number.
optional, string, max chars=50
shipping_address[line1]
Address line 1.
optional, string, max chars=180
shipping_address[line2]
Address line 2.
optional, string, max chars=150
shipping_address[line3]
Address line 3.
optional, string, max chars=150
shipping_address[city]
City.
optional, string, max chars=50
shipping_address[state_code]
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
shipping_address[state]
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
shipping_address[zip]
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
shipping_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
customer
Parameters for customer
pass parameters as customer[<param name>]
customer[vat_number]
VAT number of this customer. VIES validation will not happen for this parameter.
optional, string, max chars=20
customer[registered_for_gst]
Confirms that a customer is registered under GST. This field is available for Australia only.
optional, boolean
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
addons[id][0..n]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
addons[quantity][0..n]
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1
addons[unit_price][0..n]
Amount that will override the Addon's default price. The Plan's billing frequency will not be considered for overriding. E.g. If the Plan's billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).
optional, in cents, min=0
addons[billing_cycles][0..n]
Number of billing cycles the addon will be charged for.
optional, integer, min=1
addons[trial_end][0..n]
The time at which the trial ends for the addon. Trial end cannot be updated for addons which are attached to subscriptions. In order to use this param please contact support@chargebee.com.
optional, timestamp(UTC) in seconds
event_based_addons
Parameters for event_based_addons. Multiple event_based_addons can be passed by specifying unique indices.
pass parameters as event_based_addons[<param name>][<idx:0..n>]
event_based_addons[id][0..n]
A unique 'id' used to identify the addon.
optional, string, max chars=100
event_based_addons[quantity][0..n]
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1
event_based_addons[unit_price][0..n]
Amount that will override the Addon's default price.
optional, in cents, min=0
event_based_addons[charge_on][0..n]
Indicates when the non-recurring addon will be charged.
optional, enumerated string
Possible values are
immediatelyCharges for the addon will be applied immediately.on_eventCharge for the addon will be applied on the occurrence of a specified event.
event_based_addons[on_event][0..n]
Event on which this addon will be charged.
optional, enumerated string
Possible values are
subscription_creationAddon will be charged on subscription creation.subscription_trial_startAddon will be charged when the trial period starts.plan_activationAddon will be charged on plan activation.subscription_activationAddon will be charged on subscription activation.
event_based_addons[charge_once][0..n]
If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean, default=true
Resource object representing quote.
always returned
Creates a quote with estimated charges for purchase of a non-recurring item. Once created, the quote will be in Open state until the customer accepts it. A quote can be converted into an invoice after the customer accepts it.
Sample Request
curl  https://{site}.chargebee.com/api/v2/quotes/create_for_onetime_charges \
     -u {site_api_key}: \
     -d customer_id="8avVGOkx8U1MX" \
     -d charges[amount][1]="1000" \
     -d charges[description][1]="Support charge"
copy
curl  https://{site}.chargebee.com/api/v2/quotes/create_for_onetime_charges \
     -u {site_api_key}: \
     -d customer_id="8avVGOkx8U1MX" \
     -d charges[amount][1]="1000" \
     -d charges[description][1]="Support charge"

Sample Response [ JSON ]

{"quote": { "id": "2", "customer_id": "8avVGOkx8U1MX", "status": "open", "operation_type": "onetime_invoice", "price_type": "tax_exclusive", "valid_till": 1540883887, "date": 1540797487, "sub_total": 1400, "total": 1400, "credits_applied": 0, "amount_paid": 0, "amount_due": 1400, "updated_at": 1540797488, "resource_version": 1540797488087, "object": "quote", "line_items": [ { "id": "li_XpbGBzkR7qfEcQ2", "date_from": 1540797486, "date_to": 1540797486, "unit_amount": 200, "quantity": 2, "amount": 400, "pricing_model": "per_unit", "is_taxed": false, "tax_amount": 0, "object": "line_item", "description": "Day Pass", "entity_type": "addon", "entity_id": "day-pass", "discount_amount": 0, "item_level_discount_amount": 0 }, {..} ], "line_item_discounts": [], "taxes": [], "line_item_taxes": [], "currency_code": "USD" }}

URL Format POST

https://{site}.chargebee.com/api/v2/quotes/create_for_onetime_charges
customer_id
Identifier of the customer for which the quote needs to be created.
required, string, max chars=50
po_number
Purchase Order Number for this quote.
optional, string, max chars=100
currency_code
The currency code (ISO 4217 format) of the quote.
required if Multicurrency is enabled, string, max chars=3
coupon
The 'One Time' coupon to be applied.
optional, string, max chars=50
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
First name.
optional, string, max chars=150
shipping_address[last_name]
Last name.
optional, string, max chars=150
shipping_address[email]
Email.
optional, string, max chars=70
shipping_address[company]
Company name.
optional, string, max chars=250
shipping_address[phone]
Phone number.
optional, string, max chars=50
shipping_address[line1]
Address line 1.
optional, string, max chars=180
shipping_address[line2]
Address line 2.
optional, string, max chars=150
shipping_address[line3]
Address line 3.
optional, string, max chars=150
shipping_address[city]
City.
optional, string, max chars=50
shipping_address[state_code]
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
shipping_address[state]
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
shipping_address[zip]
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
shipping_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
addons[id][0..n]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
addons[quantity][0..n]
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1
addons[unit_price][0..n]
Amount that will override the Addon's default price. The Plan's billing frequency will not be considered for overriding. E.g. If the Plan's billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).
optional, in cents, min=0
charges
Parameters for charges. Multiple charges can be passed by specifying unique indices.
pass parameters as charges[<param name>][<idx:0..n>]
charges[amount][0..n]
The amount to be charged.
optional, in cents, min=1
charges[description][0..n]
Description for this charge.
optional, string, max chars=250
Resource object representing quote.
always returned
This API is to convert a quote to an invoice.
Sample Request
curl  https://{site}.chargebee.com/api/v2/quotes/2/convert \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/quotes/2/convert \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{ "quote": { "id": "quote001", "customer_id": "5SK0b54PR6F9LLE8g", "status": "invoiced", "operation_type": "onetime_invoice", "price_type": "tax_exclusive", "valid_till": 1540883887, "date": 1540797487, "sub_total": 1400, "total": 1400, "credits_applied": 0, "amount_paid": 0, "amount_due": 1400, "updated_at": 1540797488, "resource_version": 1540797488087, "object": "quote", "line_items": [ { "id": "li_XpbGBzkR7qfEcQ2", "date_from": 1540797486, "date_to": 1540797486, "unit_amount": 200, "quantity": 2, "amount": 400, "pricing_model": "per_unit", "is_taxed": false, "tax_amount": 0, "object": "line_item", "description": "Day Pass", "entity_type": "addon", "entity_id": "day-pass", "discount_amount": 0, "item_level_discount_amount": 0 }, {..} ], "line_item_discounts": [], "taxes": [], "line_item_taxes": [], "currency_code": "USD" }, "invoice": { "adjustment_credit_notes": [], "amount_adjusted": 0, "amount_due": 1000, "amount_paid": 0, "amount_to_collect": 1000, "applied_credits": [], "base_currency_code": "USD", "billing_address": { "first_name": "Hello", "last_name": "World", "phone": "122242222", "line1": "Wow", "line2": "Cool", "city": "Chennai", "state_code": "TN", "state": "Tamil Nadu", "country": "IN", "zip": "600041", "validation_status": "not_validated", "object": "billing_address" }, "credits_applied": 0, "currency_code": "USD", "customer_id": "5SK0b54PR6F9LLE8g", "date": 1539327099, "deleted": false, "due_date": 1539327099, "exchange_rate": 1, "first_invoice": true, "has_advance_charges": false, "id": "51", "issued_credit_notes": [], "line_items": [ { "id": "li_XpbGBzkR7qfEcQ2", "date_from": 1540797486, "date_to": 1540797486, "unit_amount": 200, "quantity": 2, "amount": 400, "pricing_model": "per_unit", "is_taxed": false, "tax_amount": 0, "object": "line_item", "description": "Day Pass", "entity_type": "addon", "entity_id": "day-pass", "discount_amount": 0, "item_level_discount_amount": 0 }, {..} ], "linked_orders": [], "linked_payments": [], "net_term_days": 0, "new_sales_amount": 1000, "object": "invoice", "price_type": "tax_exclusive", "recurring": true, "resource_version": 1539327099000, "round_off_amount": 0, "status": "not_paid", "sub_total": 1000, "subscription_id": "monthly_super_saver", "tax": 0, "total": 1000, "updated_at": 1539327099, "write_off_amount": 0 }, "customer": { "id": "5SK0b54PR6F9LLE8g", "first_name": "Hello", "last_name": "World", "email": "john@acmeinc.com", "auto_collection": "on", "net_term_days": 0, "allow_direct_debit": false, "created_at": 1539327040, "created_from_ip": "127.0.0.1", "taxability": "taxable", "updated_at": 1539327040, "pii_cleared": "active", "resource_version": 1539327040000, "deleted": false, "object": "customer", "billing_address": { "first_name": "Hello", "last_name": "World", "phone": "122242222", "line1": "Wow", "line2": "Cool", "city": "Chennai", "state_code": "TN", "state": "Tamil Nadu", "country": "IN", "zip": "600041", "validation_status": "not_validated", "object": "billing_address" }, "card_status": "valid", "primary_payment_source_id": "pm_5SK0b55NR6F9O2J5", "payment_method": { "object": "payment_method", "type": "card", "reference_id": "tok_5SK0b55NR6F9O1z4", "gateway": "chargebee", "gateway_account_id": "gw_5SK0b54PR6F92Xh2", "status": "valid" }, "promotional_credits": 0, "refundable_credits": 0, "excess_payments": 0, "unbilled_charges": 0, "preferred_currency_code": "USD" } }

URL Format POST

https://{site}.chargebee.com/api/v2/quotes/{quote_id}/convert
Resource object representing quote.
always returned
Resource object representing customer.
always returned
Resource object representing subscription.
optional
Resource object representing invoice.
optional
Resource object representing credit_note.
optional
Updates the status of the quote. Status can be updated to Accepted, Declined, and Closed.
Sample Request
curl  https://{site}.chargebee.com/api/v2/quotes/2/update_status \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/quotes/2/update_status \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"quote": { "id": "quote001", "customer_id": "5SK0b54PR6F9LLE8g", "status": "accepted", "operation_type": "onetime_invoice", "price_type": "tax_exclusive", "valid_till": 1540883887, "date": 1540797487, "sub_total": 1400, "total": 1400, "credits_applied": 0, "amount_paid": 0, "amount_due": 1400, "updated_at": 1540797488, "resource_version": 1540797488087, "object": "quote", "line_items": [ { "id": "li_XpbGBzkR7qfEcQ2", "date_from": 1540797486, "date_to": 1540797486, "unit_amount": 200, "quantity": 2, "amount": 400, "pricing_model": "per_unit", "is_taxed": false, "tax_amount": 0, "object": "line_item", "description": "Day Pass", "entity_type": "addon", "entity_id": "day-pass", "discount_amount": 0, "item_level_discount_amount": 0 }, {..} ], "line_item_discounts": [], "taxes": [], "line_item_taxes": [], "currency_code": "USD" }}

URL Format POST

https://{site}.chargebee.com/api/v2/quotes/{quote_id}/update_status
status
Status to update for the quote.
required, enumerated string
Possible values are
acceptedAccepted.declinedDeclined.closedClosed.
comment
This comment will be added to the quote.
optional, string, max chars=300
Resource object representing quote.
always returned
Sample Request
curl  https://{site}.chargebee.com/api/v2/quotes/13/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/quotes/13/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"quote": { "id": "2", "customer_id": "8avVGOkx8U1MX", "status": "open", "operation_type": "onetime_invoice", "price_type": "tax_exclusive", "valid_till": 1540883887, "date": 1540797487, "sub_total": 1400, "total": 1400, "credits_applied": 0, "amount_paid": 0, "amount_due": 1400, "updated_at": 1540797488, "resource_version": 1540797488087, "object": "quote", "line_items": [ { "id": "li_XpbGBzkR7qfEcQ2", "date_from": 1540797486, "date_to": 1540797486, "unit_amount": 200, "quantity": 2, "amount": 400, "pricing_model": "per_unit", "is_taxed": false, "tax_amount": 0, "object": "line_item", "description": "Day Pass", "entity_type": "addon", "entity_id": "day-pass", "discount_amount": 0, "item_level_discount_amount": 0 }, {..} ], "line_item_discounts": [], "taxes": [], "line_item_taxes": [], "currency_code": "USD" }}

URL Format POST

https://{site}.chargebee.com/api/v2/quotes/{quote_id}/delete
comment
Reason for deleting quote. This comment will be added to the subscription entity if the quote belongs to a subscription or added to the customer entity if the quote is associated only with a customer.
optional, string, max chars=300
Resource object representing quote.
always returned
Sample Request
curl  https://{site}.chargebee.com/api/v2/quotes/2/pdf \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/quotes/2/pdf \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"download": { "download_url": "https://cb-downloads-dev.s3.amazonaws.com/yourapp/quote/5SK0b55NR6FA3Lj6y.pdf?response-content-disposition=attachment%3Bfilename%3Dyourapp%2Fquote%2F5SK0b55NR6FA3Lj6y.pdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20181012T065321Z&X-Amz-SignedHeaders=host&X-Amz-Expires=59&X-Amz-Credential=AKIAJ3MOW2V2DPJQTCMQ%2F20181012%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=986d5f1db85c7d0d29d46c4a2e28d568734ece599b61a31572cd82fd390b12ad", "valid_till": 1539327261, "object": "download" }}

URL Format POST

https://{site}.chargebee.com/api/v2/quotes/{quote_id}/pdf
disposition_type
Determines the pdf should be rendered as inline or attachment in the browser.
optional, enumerated string, default=attachment
Possible values are
attachmentpdf is rendered as attachment in the browser.inlinepdf is rendered as inline in the browser.
Resource object representing download.
always returned