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 addon [ JSON ]

{
    "charge_type": "recurring",
    "currency_code": "USD",
    "enabled_in_portal": true,
    "id": "sms_pack",
    "invoice_name": "sample data pack",
    "is_shippable": false,
    "name": "Sms Pack",
    "object": "addon",
    "period": 1,
    "period_unit": "month",
    "price": 200,
    "pricing_model": "flat_fee",
    "resource_version": 1517505775000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "type": "on_off",
    "updated_at": 1517505775
}

API Index URL GET

https://{site}.chargebee.com/api/v2/addons

id

string, max chars=100
A unique ID for your system to identify the addon.

name

string, max chars=50
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.

description

optional, string, max chars=500
Description about the addon to show in the hosted pages & customer portal. This description will not be shown if multiple addons are added.

pricing_model

enumerated string
Defines how the charges for the addons are calculated.

Possible values are

flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThe per unit price is based on the tier that the total quantity falls in.volumeThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.stairstepA quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in.

charge_type

enumerated string, default=recurring
Type of charge

Possible values are

recurringCharges are automatically applied in sync with the billing frequency of subscription.non_recurringCharged 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

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

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

Possible values are

dayCharge based on Day(S).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).not_applicablenot 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

enumerated string, default=active
Status of the addon

Possible values are

activeOnly active addons can be applied to subscriptions.archivedNo new associations with subscriptions are allowed. Existing associations for recurring addons remain as-is and can be removed if required.deletedIndicates 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

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.

Possible values are

wholesaleTransaction is a sale to another company that will resell your product or service to another consumer.retailTransaction is a sale to an end user.consumedTransaction is for an item that is consumed directly.vendor_useTransaction 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: <category-name>: <option>. 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: <parent class>:<sub-class-1>:<sub-class-2>...
NetSuite: If you’ve categorized your products in NetSuite under Classes, provide the class name here. Use the following format: <parent class>: <sub-class-1>: <sub-class2>.... 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: <category-name>: <option>.... 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: <parent-location>:<sub-location-1>:<sub-location-2>.... 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 <parent-location> : <sub-location-1>: <sub-location-2>.... 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: <parent-department> : <sub-department-1>: <sub-department-2>.... 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.

Possible values are

yearShip based on year(s).monthShip based on month(s).weekShip based on week(s).dayShip 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.

Possible values are

webThe object was created (and is maintained) for the web channel directly in Chargebee via API or UI.app_storeThe 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_storeThe 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.

In-App Subscriptions is currently in early access. Contact eap@chargebee.com for more information.

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 set of key-value pairs stored as additional information for the subscription. 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
Show attributes[+]

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

Tier attributes

starting_unit

integer, min=1
The lower limit of a range of units for the tier

ending_unit

optional, integer
The upper limit of a range of units for the tier

price

in cents, default=0, min=0
The per-unit price for the tier when the pricing_model is tiered or volume; the total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.

starting_unit_in_decimal

optional, string, max chars=33
The decimal representation of the 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 pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.

ending_unit_in_decimal

optional, string, max chars=33
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 pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.

price_in_decimal

optional, string, max chars=39
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 the addon. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.

Create a new addon.

Sample Request

curl  https://{site}.chargebee.com/api/v2/addons \
     -u {site_api_key}:\
     -d id="sms_pack" \
     -d name="Sms Pack" \
     -d invoice_name="sample data pack" \
     -d charge_type="recurring" \
     -d price=200 \
     -d period=1 \
     -d pricing_model="flat_fee" \
     -d period_unit="month"

copy

curl  https://{site}.chargebee.com/api/v2/addons \
     -u {site_api_key}:\
     -d id="sms_pack" \
     -d name="Sms Pack" \
     -d invoice_name="sample data pack" \
     -d charge_type="recurring" \
     -d price=200 \
     -d period=1 \
     -d pricing_model="flat_fee" \
     -d period_unit="month"

# creates an addon with tiered pricing model
curl  https://{site}.chargebee.com/api/v2/addons \
     -u {site_api_key}:\
     -d id="tiered_addon" \
     -d name="Tiered Addon" \
     -d charge_type="recurring" \
     -d pricing_model="tiered" \
     -d period_unit="month" \
     -d period=1 \
     -d tiers[starting_unit][0]=1 \
     -d tiers[ending_unit][0]=10 \
     -d tiers[price][0]=100 \
     -d tiers[starting_unit][1]=11 \
     -d tiers[ending_unit][1]=20 \
     -d tiers[price][1]=300 \
     -d tiers[starting_unit][2]=21 \
     -d tiers[price][2]=500

Sample Response [ JSON ]

{"addon": {
    "charge_type": "recurring",
    "currency_code": "USD",
    "enabled_in_portal": true,
    "id": "sms_pack",
    "invoice_name": "sample data pack",
    "is_shippable": false,
    "name": "Sms Pack",
    "object": "addon",
    "period": 1,
    "period_unit": "month",
    "price": 200,
    "pricing_model": "flat_fee",
    "resource_version": 1517505775000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "type": "on_off",
    "updated_at": 1517505775
}}

{"addon": {
    "charge_type": "recurring",
    "currency_code": "USD",
    "enabled_in_portal": true,
    "id": "tiered_addon",
    "is_shippable": false,
    "name": "Tiered Addon",
    "object": "addon",
    "period": 1,
    "period_unit": "month",
    "pricing_model": "tiered",
    "resource_version": 1517505776000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "tiers": [
        {
            "ending_unit": 10,
            "object": "tier",
            "price": 100,
            "starting_unit": 1
        },
        {..}
    ],
    "type": "tiered",
    "updated_at": 1517505776
}}

URL Format POST

https://{site}.chargebee.com/api/v2/addons

id

required, string, max chars=100
A unique ID for your system to identify the addon.

name

required, string, max chars=50
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.

description

optional, string, max chars=500
Description about the addon to show in the hosted pages & customer portal. This description will not be shown if multiple addons are added.

charge_type

required, enumerated string, default=recurring
Type of charge.

Possible values are

recurringCharges are automatically applied in sync with the billing frequency of subscription.non_recurringCharged 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 if Multicurrency is enabled, 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

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

Possible values are

dayCharge based on Day(S)weekCharge based on week(s)monthCharge based on month(s)yearCharge based on year(s)not_applicablenot applicable for this addon

pricing_model

optional, enumerated string
Defines how the charges for the addons are calculated.

Possible values are

unit

enabled_in_portal

optional, boolean, default=true
If enabled, customers can select this addon using the 'Change Subscription' option in the customer portal.

taxable

tax_profile_id

optional, string, max chars=50
Tax profile of the addon.

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.

Possible values are

wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction 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

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.

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.

meta_data

optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.

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: <category-name>: <option>. 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: <parent class>:<sub-class-1>:<sub-class-2>...
NetSuite: If you’ve categorized your products in NetSuite under Classes, provide the class name here. Use the following format: <parent class>: <sub-class-1>: <sub-class2>.... 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: <category-name>: <option>.... 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: <parent-location>:<sub-location-1>:<sub-location-2>.... 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 <parent-location> : <sub-location-1>: <sub-location-2>.... 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: <parent-department> : <sub-department-1>: <sub-department-2>.... 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.

Possible values are

yearShip based on year(s)monthShip based on month(s)weekShip based on week(s)dayShip based on day(s)

included_in_mrr

show_description_in_invoices

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.

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.

status

optional, enumerated string, default=active
Status of the addon.

Possible values are

activeOnly active addons can be applied to subscriptionsarchivedNo new associations with subscriptions are allowed. Existing associations for recurring addons remain as-is and can be removed if required.

tiers

Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]

tiers[starting_unit][0..n]

optional, integer, min=1
The lower limit of a range of units for the tier

tiers[ending_unit][0..n]

optional, integer
The upper limit of a range of units for the tier

tiers[price][0..n]

optional, in cents, default=0, min=0
The per-unit price for the tier when the pricing_model is tiered or volume; the total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.

tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33
The decimal representation of the 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. Applicable only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.

tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33
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. Applicable only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.

tiers[price_in_decimal][0..n]

optional, string, max chars=39
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 the plan. The value is in major units of the currency. Applicable when the plan is quantity-based and multi-decimal pricing is enabled.

addon

always returned
Resource object representing addon

When updating addons that already have an invoice or a subscription linked to it, you can only update the following parameters:

name
invoice_name
price
included_in_mrr
meta_data

Sample Request

curl  https://{site}.chargebee.com/api/v2/addons/sub_reports \
     -u {site_api_key}:\
     -d invoice_name="sample data pack" \
     -d price=100

copy

curl  https://{site}.chargebee.com/api/v2/addons/sub_reports \
     -u {site_api_key}:\
     -d invoice_name="sample data pack" \
     -d price=100

Sample Response [ JSON ]

{"addon": {
    "charge_type": "recurring",
    "currency_code": "USD",
    "enabled_in_portal": true,
    "id": "sub_reports",
    "invoice_name": "sample data pack",
    "is_shippable": false,
    "name": "sub_Reports",
    "object": "addon",
    "period": 1,
    "period_unit": "month",
    "price": 100,
    "pricing_model": "flat_fee",
    "resource_version": 1517505781000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "type": "on_off",
    "updated_at": 1517505781
}}

URL Format POST

https://{site}.chargebee.com/api/v2/addons/{addon_id}

name

optional, string, max chars=50
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.

description

optional, string, max chars=500
Description about the addon to show in the hosted pages & customer portal. This description will not be shown if multiple addons are added.

charge_type

optional, enumerated string
Type of charge.

Possible values are

recurringCharges are automatically applied in sync with the billing frequency of subscription.non_recurringCharged 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

optional, string, max chars=3
The currency code (ISO 4217 format) of the addon. Applicable if Multicurrency is enabled.

period

optional, integer, min=1
Applicable only for recurring-addons. Along with 'period_unit' decides the term-price of this addon.

period_unit

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

Possible values are

dayCharge based on Day(S)weekCharge based on week(s)monthCharge based on month(s)yearCharge based on year(s)not_applicablenot applicable for this addon

pricing_model

optional, enumerated string
Defines how the charges for the addons are calculated.

Possible values are

unit

enabled_in_portal

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

taxable

optional, boolean
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.

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.

Possible values are

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

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.

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.

meta_data

optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.

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: <category-name>: <option>. 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: <parent class>:<sub-class-1>:<sub-class-2>...
NetSuite: If you’ve categorized your products in NetSuite under Classes, provide the class name here. Use the following format: <parent class>: <sub-class-1>: <sub-class2>.... 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: <category-name>: <option>.... 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: <parent-location>:<sub-location-1>:<sub-location-2>.... 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 <parent-location> : <sub-location-1>: <sub-location-2>.... 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: <parent-department> : <sub-department-1>: <sub-department-2>.... 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
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.

Possible values are

yearShip based on year(s)monthShip based on month(s)weekShip based on week(s)dayShip based on day(s)

included_in_mrr

show_description_in_invoices

optional, boolean
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
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.

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.

tiers

Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]

tiers[starting_unit][0..n]

optional, integer, min=1
The lower limit of a range of units for the tier

tiers[ending_unit][0..n]

optional, integer
The upper limit of a range of units for the tier

tiers[price][0..n]

optional, in cents, min=0
The per-unit price for the tier when the pricing_model is tiered or volume; the total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.

tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33
The decimal representation of the 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. Applicable only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.

tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33
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. Applicable only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.

tiers[price_in_decimal][0..n]

optional, string, max chars=39
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 the plan. The value is in major units of the currency. Applicable when the plan is quantity-based and multi-decimal pricing is enabled.

addon

always returned
Resource object representing addon

List the addons. This returns all your current active and archived addons.

Sample Request

curl  https://{site}.chargebee.com/api/v2/addons \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3 \
     --data-urlencode status[is]="active"

copy

curl  https://{site}.chargebee.com/api/v2/addons \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3 \
     --data-urlencode status[is]="active"

Sample Response [ JSON ]

{
    "list": [
        {"addon": {
            "charge_type": "recurring",
            "currency_code": "USD",
            "enabled_in_portal": true,
            "id": "tiered_addon",
            "is_shippable": false,
            "name": "Tiered Addon",
            "object": "addon",
            "period": 1,
            "period_unit": "month",
            "pricing_model": "tiered",
            "resource_version": 1517505776000,
            "show_description_in_invoices": false,
            "show_description_in_quotes": false,
            "status": "active",
            "taxable": true,
            "tiers": [
                {
                    "ending_unit": 10,
                    "object": "tier",
                    "price": 100,
                    "starting_unit": 1
                },
                {..}
            ],
            "type": "tiered",
            "updated_at": 1517505776
        }},
        {..}
    ],
    "next_offset": "[\"150000000949\"]"
}

URL Format GET

https://{site}.chargebee.com/api/v2/addons

limit

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset

optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.

include_deleted

optional, boolean, default=false
If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

optional, string filter
A unique ID for your system to identify the addon.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "support_charge"

name[<operator>]

optional, string filter
The display name used in web interface for identifying the addon.
Supported operators : is, is_not, starts_with, in, not_in

Example → name[is] = "Support Charge"

pricing_model[<operator>]

optional, enumerated string filter
Defines how the charges for the addons are calculated. Possible values are : flat_fee, per_unit, tiered, volume, stairstep.
Supported operators : is, is_not, in, not_in

Example → pricing_model[is] = "flat_fee"

charge_type[<operator>]

optional, enumerated string filter
Type of charge. Possible values are : recurring, non_recurring.
Supported operators : is, is_not, in, not_in

Example → charge_type[is] = "recurring"

price[<operator>]

optional, in cents filter
Addon price is calculated based on the addon type and charge type. Learn more. The unit depends on the type of currency.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → price[is] = "1300"

period[<operator>]

optional, integer filter
Applicable only for recurring-addons. Along with 'period_unit' decides the term-price of this addon.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → period[is] = "3"

period_unit[<operator>]

optional, enumerated string filter
Applicable only for recurring-addons. Along with 'period' decides the term-price of this addon. Possible values are : day, week, month, year, not_applicable.
Supported operators : is, is_not, in, not_in

Example → period_unit[is] = "month"

status[<operator>]

optional, enumerated string filter
Status of the addon. Possible values are : active, archived, deleted.
Supported operators : is, is_not, in, not_in

Example → status[is] = "active"

updated_at[<operator>]

optional, timestamp(UTC) in seconds filter
To filter based on updated at. This attribute will be present only if the resource has been updated after 2016-11-09.
Supported operators : after, before, on, between

Example → updated_at[after] = "1243545465"

currency_code[<operator>]

optional, string filter
The currency code (ISO 4217 format) of the addon.
Supported operators : is, is_not, starts_with, in, not_in

Example → currency_code[is] = "USD"

channel[<operator>]

optional, enumerated string filter
The subscription channel this object originated from and is maintained in. Possible values are : web, app_store, play_store.
Supported operators : is, is_not, in, not_in

Example → channel[is] = "APP STORE"

addon

always returned
Resource object representing addon

next_offset

optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.

Retrieve a specific addon using the id.

Sample Request

curl  https://{site}.chargebee.com/api/v2/addons/sub_reports \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/addons/sub_reports \
     -u {site_api_key}:

Sample Response [ JSON ]

{"addon": {
    "charge_type": "recurring",
    "currency_code": "USD",
    "enabled_in_portal": true,
    "id": "sub_reports",
    "is_shippable": false,
    "name": "sub_Reports",
    "object": "addon",
    "period": 1,
    "period_unit": "month",
    "price": 750,
    "pricing_model": "flat_fee",
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "type": "on_off"
}}

URL Format GET

https://{site}.chargebee.com/api/v2/addons/{addon_id}

addon

always returned
Resource object representing addon

Sample admin console URL

https://{site}.chargebee.com/admin-console/addons/123x

When an addon that already has subscriptions/invoices linked to it is deleted, it does not get completely purged but is instead moved to "Archived" state. No other subscriptions can use this addon but subscriptions already on it will continue to renew. Once an addon has been archived, it cannot be edited or used again and the addon cannot be un-archived.

If no subscriptions or invoices are linked to an addon, the addon will be permanently deleted from your Chargebee site. This action cannot be undone.

If an addon that is an applicable item for a coupon is deleted, then the addon will be removed from that coupon's list of applicable items.

Archiving an addon will not affect coupons in anyway.

Sample Request

curl  https://{site}.chargebee.com/api/v2/addons/test/delete \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/addons/test/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"addon": {
    "charge_type": "recurring",
    "currency_code": "USD",
    "enabled_in_portal": true,
    "id": "test",
    "invoice_name": "sample data pack",
    "is_shippable": false,
    "name": "Test",
    "object": "addon",
    "period": 1,
    "period_unit": "month",
    "price": 200,
    "pricing_model": "flat_fee",
    "resource_version": 1600968177768,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "deleted",
    "taxable": true,
    "type": "on_off",
    "updated_at": 1600968177
}}

URL Format POST

https://{site}.chargebee.com/api/v2/addons/{addon_id}/delete

addon

always returned
Resource object representing addon

Creates an addon in this site by copying its configurations from another site. Copying of archived addons is not supported.

Note: The attribute tax_profile_id is not copied. In effect, if the plan is taxable, it will be mapped to the Primary tax profile.

This API is not enabled for live sites by default. Please contact support to get this enabled.

Sample Request

curl  https://{site}.chargebee.com/api/v2/addons/copy \
     -u {site_api_key}:\
     -d from_site="merchant-test" \
     -d id_at_from_site="additional_overage_invoices_one_time"

copy

curl  https://{site}.chargebee.com/api/v2/addons/copy \
     -u {site_api_key}:\
     -d from_site="merchant-test" \
     -d id_at_from_site="additional_overage_invoices_one_time"

Sample Response [ JSON ]

{"addon": {
    "charge_type": "non_recurring",
    "currency_code": "USD",
    "enabled_in_portal": false,
    "id": "additional_overage_invoices_one_time",
    "invoice_name": "Overage charges for Invoices",
    "is_shippable": false,
    "meta_data": {
        "bucket_size": 50,
        "price_model": "bucket"
    },
    "name": "Additional Overage Invoices - One Time",
    "object": "addon",
    "period": 1,
    "period_unit": "month",
    "price": 1000,
    "pricing_model": "per_unit",
    "resource_version": 1517505774000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "type": "quantity",
    "unit": "50 invoices",
    "updated_at": 1517505774
}}

URL Format POST

https://{site}.chargebee.com/api/v2/addons/copy

from_site

required, string, max chars=50
Your Chargebee site name having the addon to be copied.
Note: Unless you are copying from a twin site (acme & acme-test are twin sites), contact support to have this allow-listed.

id_at_from_site

required, string, max chars=100
Id of the addon to be copied. The new addon created in this site will have the same Id.

id

optional, string, max chars=100
Id of copied addon in this site.

for_site_merging

optional, boolean, default=false
If copy action is performed as part of Chargebee site merge action, pass the value as true.

addon

always returned
Resource object representing addon

Unarchives a specific addon using the id.

Sample Request

curl  https://{site}.chargebee.com/api/v2/addons/net_pack/unarchive \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/addons/net_pack/unarchive \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"addon": {
    "charge_type": "recurring",
    "currency_code": "USD",
    "enabled_in_portal": true,
    "id": "net_pack",
    "is_shippable": false,
    "name": "Net pack",
    "object": "addon",
    "period": 1,
    "period_unit": "month",
    "price": 0,
    "pricing_model": "flat_fee",
    "resource_version": 1517505780000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "type": "on_off",
    "updated_at": 1517505780
}}

URL Format POST

https://{site}.chargebee.com/api/v2/addons/{addon_id}/unarchive

addon

always returned
Resource object representing addon

Sample addon [ JSON ]

API Index URL GET

Addon attributes

Create an addon¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Update an addon¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

List addons¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Retrieve an addon¶

Sample Response [ JSON ]

URL Format GET

Returns

Sample admin console URL

Delete an addon¶

Sample Response [ JSON ]

URL Format POST

Returns

Copy an Addon¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Unarchive an addon¶

Sample Response [ JSON ]

URL Format POST

Returns