Addons

Addons are additional charges applied to a subscription apart from the base plan charge. The addons can be recurring or non-recurring. A recurring addon included in a subscription is charged as per billing frequency of subscription. A non-recurring addon included in subscription will be charged immediately and only once. And a non-recurring addon is NOT pro-rated based on billing cycle, whereas a recurring addon is automatically pro-rated based on billing cycle.

Sample AddonJSON

Addons attributes

required, string, max chars=100

A unique ID for your system to identify the addon.

name

required, string, max chars=100

The display name used in web interface for identifying the addon.

invoice_name

optional, string, max chars=100

Display name used in invoice. If it is not configured then name is used in invoice.

pricing_model

required, enumerated string

Defines how the charges for the addons are calculated.

flat_fee

A fixed price that is not quantity-based.

per_unit

A fixed price per unit quantity.

tiered

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

volume

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

stairstep

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

charge_type

required, enumerated string, default=recurring

Type of charge

recurring

Charges are automatically applied in sync with the billing frequency of subscription.

non_recurring

Charged immediately and only once every time it is applied.

price

optional, in cents, min=0

Addon price is calculated based on the addon type and charge type. Learn more. The unit depends on the type of currency .

currency_code

required, string, max chars=3

The currency code (ISO 4217 format) of the addon

period

optional, integer, min=1

Applicable only for recurring-addons. Along with 'period_unit' decides the term-price of this addon.

period_unit

required, enumerated string

Applicable only for recurring-addons. Along with 'period' decides the term-price of this addon

day

Charge based on Day(S)

week

Charge based on week(s)

month

Charge based on month(s)

year

Charge based on year(s)

not_applicable

not applicable for this addon

unit

optional, string, max chars=30

Specifies the type of quantity. For example, if the addon price is $10 and 'agent' is the unit of measure, the addon will be $10/agent. Applicable only for quantity type addons.

status

required, enumerated string, default=active

Status of the addon

active

Only active addons can be applied to subscriptions

archived

No new associations with subscriptions are allowed. Existing associations for recurring addons remain as-is and can be removed if required.

deleted

Indicates the addon has been deleted.

archived_at

optional, timestamp(UTC) in seconds

Time at which the plan was moved to archived status.

enabled_in_portal

required, boolean, default=true

If enabled, customers can select this addon using the 'Change Subscription' option in the customer portal.

tax_code

optional, string, max chars=50

The Avalara tax codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's AvaTax for Sales integration .

hsn_code

optional, string, max chars=50

The HSN code to which the item is mapped for calculating the customer's tax in India. Applicable only when both of the following conditions are true:

India has been enabled as a Tax Region. (An error is returned when this condition is not true.)
The AvaTax for Sales integration has been enabled in Chargebee.

taxjar_product_code

optional, string, max chars=50

The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's TaxJar integration .

avalara_sale_type

optional, enumerated string

Indicates the type of sale carried out. This is applicable only if you use Chargebee's AvaTax for Communications integration.

wholesale

Transaction is a sale to another company that will resell your product or service to another consumer

retail

Transaction is a sale to an end user

consumed

Transaction is for an item that is consumed directly

vendor_use

Transaction is for an item that is subject to vendor use tax

avalara_transaction_type

optional, integer

Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee's AvaTax for Communications integration.

avalara_service_type

optional, integer

Indicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee's AvaTax for Communications integration.

sku

optional, string, max chars=100

The field is used as Product name/code in your third party accounting application. Chargebee will use it as an alternate name in your accounting application.

accounting_code

optional, string, max chars=100

This field is to capture the Account code setup in your Accounting system for integration purposes only.

accounting_category1

optional, string, max chars=100

Used exclusively with the following accounting integrations

Xero: If you've categorized your products in Xero, provide the category name and option. Use the format: : . For example:Location: Singapore.
QuickBooks: If you've categorized your product sales in QuickBooks according to Classes, provide the class name here. Use the following format: ::...
NetSuite: If you've categorized your products in NetSuite under Classes, provide the class name here. Use the following format: : : .... For example: Services : Plan.
Intacct: If you've classified your products in Intacct under Locations, provide the name of the Location here.

accounting_category2

optional, string, max chars=100

Used exclusively with the following accounting integrations

Xero: If you've categorized your products in Xero, then provide the second category name and option here. Use the format: : .... For example, Region: South
QuickBooks: If you've categorized your product sales in QuickBooks according to Location, provide the Location name here. Use the following format: ::.... For example: Location: North America: Canada
NetSuite: If you've categorized your products in NetSuite under Locations, provide the location name here. Use the following format : : .... For example: NA:US:CA
Intacct: If you've classified your products in Intacct under Dimensions, provide the value of the Dimension here.

accounting_category3

optional, string, max chars=100

Used exclusively with the following accounting integrations

NetSuite: If you've categorized your products in NetSuite under Departments, pass the department name here. Use the following format: : : .... For example: Production: Assembly.
Intacct: If you've classified your products in Intacct under multiple Dimensions, provide the value of the second Dimension here.

accounting_category4

optional, string, max chars=100

Used exclusively with the following accounting integrations

NetSuite: Provide the "Revenue Recognition Rule Id" for the product from NetSuite.
Intacct: If you have configured "Revenue Recognition Templates" for products in Intacct, provide the template ID for the product.

is_shippable

optional, boolean, default=false

If enabled, charges for this plan/addon will be added to orders.

shipping_frequency_period

optional, integer, min=1

Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.

shipping_frequency_period_unit

optional, enumerated string

Defines the shipping frequency in association with shipping period.

year

Ship based on year(s)

month

Ship based on month(s)

week

Ship based on week(s)

day

Ship based on day(s)

resource_version

optional, long

Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.

updated_at

optional, timestamp(UTC) in seconds

Timestamp indicating when this addon was last updated. This attribute will be present only if the resource has been updated after 2016-11-09.

price_in_decimal

optional, string, max chars=39

The price of the addon when the pricing_model is flat_fee. When the pricing model is per_unit , it is the price per unit quantity of the item. Not applicable for the other pricing models. The value is in decimal and in major units of the currency. Also, this is only applicable when multi-decimal pricing is enabled.

This price is for the period of the addon. When attached to a plan, the addon is billed for the billing period of the plan. Learn more is enabled.

included_in_mrr

optional, boolean

The addon is included in MRR calculations for your site. This attribute is only applicable for addons of charge_type = non_recurring and when the feature is enabled in Chargebee. Note: If the site-level setting is to exclude non-recurring addons from MRR calculations, this value is always returned false .

channel

optional, enumerated string

The subscription channel this object originated from and is maintained in.

web

The object was created (and is maintained) for the web channel directly in Chargebee via API or UI.

app_store

The object data is synchronized with data from in-app subscription(s) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.

play_store

The object data is synchronized with data from in-app subscription(s) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.

proration_type

optional, enumerated string, default=site_default

Note Applicable only for addons with pricing_model = per_unit.

Specifies how to manage charges or credits for the addon during a subscription update or estimating a subscription update.

site_default

Use the site-wide proration setting .

partial_term

Prorate the charges or credits for the rest of the current term.

full_term

Charge the full price of the addon item price or give the full credit. Don't apply any proration.

invoice_notes

optional, string, max chars=2000

A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.

taxable

optional, boolean, default=true

Specifies whether taxes apply to this addon. This value is set and returned even if Taxes have been disabled in Chargebee. However, the value is effective only while Taxes are enabled.

tax_profile_id

optional, string, max chars=50

Tax profile of the addon.

meta_data

optional, jsonobject

A collection of key-value pairs that provides extra information about the addon.

Note: There's a character limit of 65,535.

Learn more .

show_description_in_invoices

optional, boolean, default=false

Whether the addon description should be shown on invoice PDFs. If this Boolean is changed, only invoices generated (or regenerated ) after the change are affected; past invoices are not.

show_description_in_quotes

optional, boolean, default=false

Whether the addon description should be shown on quote PDFs. If this Boolean is changed, only quotes created after the change are affected; past quotes are not.

tiers

optional, list of tier

List of tiers for this addon(applicable only if it is tiered/volume/stairtstep pricing

tax_providers_fields

optional, list of tax_providers_field

List of vendor specific tax related information.