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 ]

{ "id": "ssl", "name": "SSL", "type": "on_off", "charge_type": "recurring", "price": 495, "period": 1, "period_unit": "month", "status": "active", "enabled_in_portal": true, "object": "addon", "currency_code": "USD", "taxable": true }

API Index URL GET

https://{site}.chargebee.com/api/v2/addons
id
A unique ID for your system to identify the addon.
string, max chars=100
name
The display name used in web interface for identifying the addon.
string, max chars=50
invoice_name
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100
description
Additional text displayed in the customer portal to describe the addon.
optional, string, max chars=500
type
Select "On-Off" to charge a flat fee or "Quantity" for unit based charges.
enumerated string
Possible values are
on_offAddon that does not have any quantity associated and can only be enabled or disabled. Example: On call support at $99 per month.quantityAllows user to specify how many units of that item they want to buy. Example: 2 additional support agents at $10 each.
charge_type
Type of charge.
enumerated string, default=recurring
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
Addon price is calculated based on the addon type and charge type. Learn more.
in cents, default=0, min=0
currency_code
The currency code (ISO 4217 format) of the addon.
string, max chars=3
period
Applicable only for recurring-addons. Along with 'period_unit' decides the term-price of this addon.
optional, integer, min=1
period_unit
Applicable only for recurring-addons. Along with 'period' decides the term-price of this addon.
enumerated string
Possible values are
weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).not_applicablenot applicable for this addon.
unit
Specifies the type of quantity. For example, if addon price is $10 and "agent" is the unit of measure, it will be displayed as "$10/agent".
Applicable only for quantity type addons.
optional, string, max chars=30
status
Status of the addon.
enumerated string, default=active
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
Time at which the plan was moved to archived status.
optional, timestamp(UTC) in seconds
enabled_in_portal
If enabled, customers can select this addon using the 'Change Subscription' option in the customer portal.
boolean, default=true
tax_code
The Avalara tax codes to which items are mapped to should be provided here. Applicable only for Avalara.
optional, string, max chars=50
sku
This field is used as Product ID or Code esp. for integration purposes.
optional, string, max chars=100
accounting_code
This field is to capture the Account code setup in your Accounting system for integration purposes only.
optional, string, max chars=100
accounting_category1
The name of the category of your product in Xero. If you've integrated with QuickBooks, this will be the "Class". Use the format "<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
accounting_category2
The name of the category of your product in Xero. Use the format<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
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 addon was last updated. This attribute will be present only if the resource has been updated after 2016-11-09.
optional, timestamp(UTC) in seconds
invoice_notes
Invoice Notes for this resource. Read More.
optional, string, max chars=1000
taxable
Specifies if the addon should be taxed or not.
optional, boolean, default=true
tax_profile_id
Tax profile of the addon.
optional, string, max chars=50
meta_data
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
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 period_unit="month" \
     -d type="on_off"
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 period_unit="month" \
     -d type="on_off"

Sample Response [ JSON ]

{"addon": { "id": "sms_pack", "name": "Sms Pack", "invoice_name": "sample data pack", "type": "on_off", "charge_type": "recurring", "price": 200, "period": 1, "period_unit": "month", "status": "active", "enabled_in_portal": true, "updated_at": 1482763724, "resource_version": 1482763724000, "object": "addon", "currency_code": "USD", "taxable": true }}

URL Format POST

https://{site}.chargebee.com/api/v2/addons
id
A unique ID for your system to identify the addon.
required, string, max chars=100
name
The display name used in web interface for identifying the addon.
required, string, max chars=50
invoice_name
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100
description
Additional text displayed in the customer portal to describe the addon.
optional, string, max chars=500
charge_type
Type of charge.
required, enumerated string, default=recurring
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
Addon price is calculated based on the addon type and charge type. Learn more.
optional, in cents, default=0, min=0
currency_code
The currency code (ISO 4217 format) of the addon.
required if Multicurrency is enabled, string, max chars=3
period
Applicable only for recurring-addons. Along with 'period_unit' decides the term-price of this addon.
optional, integer, min=1
period_unit
Applicable only for recurring-addons. Along with 'period' decides the term-price of this addon.
optional, enumerated string
Possible values are
weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).not_applicablenot applicable for this addon.
type
Select "On-Off" to charge a flat fee or "Quantity" for unit based charges.
required, enumerated string
Possible values are
on_offAddon that does not have any quantity associated and can only be enabled or disabled. Example: On call support at $99 per month.quantityAllows user to specify how many units of that item they want to buy. Example: 2 additional support agents at $10 each.
unit
Specifies the type of quantity. For example, if addon price is $10 and "agent" is the unit of measure, it will be displayed as "$10/agent".
Applicable only for quantity type addons.
optional, string, max chars=30
enabled_in_portal
If enabled, customers can select this addon using the 'Change Subscription' option in the customer portal.
optional, boolean, default=true
taxable
Specifies if the addon should be taxed or not.
optional, boolean, default=true
tax_profile_id
Tax profile of the addon.
optional, string, max chars=50
tax_code
The Avalara tax codes to which items are mapped to should be provided here. Applicable only for Avalara.
optional, string, max chars=50
invoice_notes
Invoice Notes for this resource. Read More.
optional, string, max chars=1000
meta_data
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
sku
This field is used as Product ID or Code esp. for integration purposes.
optional, string, max chars=100
accounting_code
This field is to capture the Account code setup in your Accounting system for integration purposes only.
optional, string, max chars=100
accounting_category1
The name of the category of your product in Xero. If you've integrated with QuickBooks, this will be the "Class". Use the format "<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
accounting_category2
The name of the category of your product in Xero. Use the format<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
Resource object representing addon.
always returned

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

  • id
  • name
  • invoice_name
  • meta_data

When updating the addon id, only the updated addon id will be returned upon success. Reference to the old addon id will not be available. You also need to ensure that you update the new addon ID in your system.

Sample Request
curl  https://{site}.chargebee.com/api/v2/addons/ssl \
     -u {site_api_key}: \
     -d invoice_name="sample data pack"
copy
curl  https://{site}.chargebee.com/api/v2/addons/ssl \
     -u {site_api_key}: \
     -d invoice_name="sample data pack"

Sample Response [ JSON ]

{"addon": { "id": "ssl", "name": "SSL", "invoice_name": "sample data pack", "type": "on_off", "charge_type": "recurring", "price": 495, "period": 1, "period_unit": "month", "status": "active", "enabled_in_portal": true, "updated_at": 1482763724, "resource_version": 1482763724000, "object": "addon", "currency_code": "USD", "taxable": true }}

URL Format POST

https://{site}.chargebee.com/api/v2/addons/{addon_id}
id
A unique ID for your system to identify the addon.
optional, string, max chars=100
name
The display name used in web interface for identifying the addon.
optional, string, max chars=50
invoice_name
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100
description
Additional text displayed in the customer portal to describe the addon.
optional, string, max chars=500
charge_type
Type of charge.
optional, enumerated string
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
Addon price is calculated based on the addon type and charge type. Learn more.
optional, in cents, min=0
currency_code
The currency code (ISO 4217 format) of the addon. Applicable if Multicurrency is enabled.
optional, string, max chars=3
period
Applicable only for recurring-addons. Along with 'period_unit' decides the term-price of this addon.
optional, integer, min=1
period_unit
Applicable only for recurring-addons. Along with 'period' decides the term-price of this addon.
optional, enumerated string
Possible values are
weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).not_applicablenot applicable for this addon.
type
Select "On-Off" to charge a flat fee or "Quantity" for unit based charges.
optional, enumerated string
Possible values are
on_offAddon that does not have any quantity associated and can only be enabled or disabled. Example: On call support at $99 per month.quantityAllows user to specify how many units of that item they want to buy. Example: 2 additional support agents at $10 each.
unit
Specifies the type of quantity. For example, if addon price is $10 and "agent" is the unit of measure, it will be displayed as "$10/agent".
Applicable only for quantity type addons.
optional, string, max chars=30
enabled_in_portal
If enabled, customers can select this addon using the 'Change Subscription' option in the customer portal.
optional, boolean
taxable
Specifies if the addon should be taxed or not.
optional, boolean
tax_profile_id
Tax profile of the addon.
optional, string, max chars=50
tax_code
The Avalara tax codes to which items are mapped to should be provided here. Applicable only for Avalara.
optional, string, max chars=50
invoice_notes
Invoice Notes for this resource. Read More.
optional, string, max chars=1000
meta_data
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
sku
This field is used as Product ID or Code esp. for integration purposes.
optional, string, max chars=100
accounting_code
This field is to capture the Account code setup in your Accounting system for integration purposes only.
optional, string, max chars=100
accounting_category1
The name of the category of your product in Xero. If you've integrated with QuickBooks, this will be the "Class". Use the format "<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
accounting_category2
The name of the category of your product in Xero. Use the format<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
Resource object representing addon.
always returned
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="5" \
     --data-urlencode type[is]="on_off" \
     --data-urlencode status[is]="active"
copy
curl  https://{site}.chargebee.com/api/v2/addons \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5" \
     --data-urlencode type[is]="on_off" \
     --data-urlencode status[is]="active"

Sample Response [ JSON ]

{ "list": [ {"addon": { "id": "sms_pack", "name": "Sms Pack", "invoice_name": "sample data pack", "type": "on_off", "charge_type": "recurring", "price": 200, "period": 1, "period_unit": "month", "status": "active", "enabled_in_portal": true, "updated_at": 1482763724, "resource_version": 1482763724000, "object": "addon", "currency_code": "USD", "taxable": true }}, {..} ], "next_offset": "[\"75000000152\"]" }

URL Format GET

https://{site}.chargebee.com/api/v2/addons
limit
Limits the number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
To filter based on Addon Id.
Supported operators : is, is_not, starts_with, in, not_in

Example id[is_not] = "support_charge"
optional, string filter
name[<operator>]
To filter based on Addon Name.
Supported operators : is, is_not, starts_with, in, not_in

Example name[is_not] = "Support Charge"
optional, string filter
type[<operator>]
To filter based on Addon Type. Possible values are : on_off, quantity.
Supported operators : is, is_not, in, not_in

Example type[is] = "on_off"
optional, enumerated string filter
charge_type[<operator>]
To filter based on Addon Charge Type. Possible values are : recurring, non_recurring.
Supported operators : is, is_not, in, not_in

Example charge_type[is] = "recurring"
optional, enumerated string filter
price[<operator>]
To filter based on Addon Price.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example price[lte] = "1300"
optional, in cents filter
period[<operator>]
To filter based on Addon Period.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example period[is_not] = "3"
optional, integer filter
period_unit[<operator>]
To filter based on Addon Period Unit. Possible values are : week, month, year, not_applicable.
Supported operators : is, is_not, in, not_in

Example period_unit[is] = "month"
optional, enumerated string filter
status[<operator>]
To filter based on Addon State. Possible values are : active, archived, deleted.
Supported operators : is, is_not, in, not_in

Example status[is_not] = "active"
optional, enumerated string filter
updated_at[<operator>]
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[before] = "1243545465"
optional, timestamp(UTC) in seconds filter
Resource object representing addon.
always returned
next_offset
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”.
optional, string, max chars=1000
Retrieve a specific addon using the id.
Sample Request
curl  https://{site}.chargebee.com/api/v2/addons/ssl \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/addons/ssl \
     -u {site_api_key}:

Sample Response [ JSON ]

{"addon": { "id": "ssl", "name": "SSL", "invoice_name": "sample data pack", "type": "on_off", "charge_type": "recurring", "price": 495, "period": 1, "period_unit": "month", "status": "active", "enabled_in_portal": true, "updated_at": 1482763724, "resource_version": 1482763724000, "object": "addon", "currency_code": "USD", "taxable": true }}

URL Format GET

https://{site}.chargebee.com/api/v2/addons/{addon_id}
Resource object representing addon.
always returned

Sample admin console URL

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

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/ssl/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/addons/ssl/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"addon": { "id": "ssl", "name": "SSL", "invoice_name": "sample data pack", "type": "on_off", "charge_type": "recurring", "price": 495, "period": 1, "period_unit": "month", "status": "deleted", "enabled_in_portal": true, "updated_at": 1482763724, "resource_version": 1482763724000, "object": "addon", "currency_code": "USD", "taxable": true }}

URL Format POST

https://{site}.chargebee.com/api/v2/addons/{addon_id}/delete
Resource object representing addon.
always returned

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@chargebee.com to get this enabled.
Sample Request
curl  https://{site}.chargebee.com/api/v2/addons/copy \
     -u {site_api_key}: \
     -d from_site="acme-test" \
     -d id_at_from_site="ssl"
copy
curl  https://{site}.chargebee.com/api/v2/addons/copy \
     -u {site_api_key}: \
     -d from_site="acme-test" \
     -d id_at_from_site="ssl"

Sample Response [ JSON ]

{"addon": { "id": "cbdemo_additionaluser", "name": "Additional users", "invoice_name": "Additional users", "description": "Pay for each additional user apart from your base plan.", "type": "quantity", "charge_type": "recurring", "price": 1000, "period": 1, "period_unit": "month", "unit": "user", "status": "active", "enabled_in_portal": true, "updated_at": 1482763724, "resource_version": 1482763724000, "object": "addon", "currency_code": "USD", "taxable": false }}

URL Format POST

https://{site}.chargebee.com/api/v2/addons/copy
from_site
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), please contact support@chargebee.com to have this white-listed.
required, string, max chars=50
id_at_from_site
Id of the addon to be copied. The new addon created in this site will have the same Id.
required, string, max chars=100
Resource object representing addon.
always returned
Unarchives a specific addon using the id.
Sample Request
curl  https://{site}.chargebee.com/api/v2/addons/ssl/unarchive \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/addons/ssl/unarchive \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"addon": { "id": "additional_users_2", "name": "Additional Users 2", "type": "quantity", "charge_type": "recurring", "price": 95, "period": 1, "period_unit": "month", "unit": "per GB", "status": "active", "enabled_in_portal": true, "updated_at": 1482763724, "resource_version": 1482763724000, "object": "addon", "currency_code": "USD", "taxable": true }}

URL Format POST

https://{site}.chargebee.com/api/v2/addons/{addon_id}/unarchive
Resource object representing addon.
always returned