You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).

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", "taxable": true }

API Index URL GET

https://{site}.chargebee.com/api/v1/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
Description about the addon to show in the hosted pages & customer portal.
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.quantityCharges this price for every unit of the addon. 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.
optional, in cents, min=0
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
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
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/v1/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"
copy
curl  https://{site}.chargebee.com/api/v1/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"

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, "object": "addon", "taxable": true }}

URL Format POST

https://{site}.chargebee.com/api/v1/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
Description about the addon to show in the hosted pages & customer portal.
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, min=0
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.quantityCharges this price for every unit of the addon. 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
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
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:

  • name
  • invoice_name
  • price
Sample Request
curl  https://{site}.chargebee.com/api/v1/addons/ssl \
     -u {site_api_key}: \
     -d invoice_name="sample data pack"
copy
curl  https://{site}.chargebee.com/api/v1/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, "object": "addon", "taxable": true }}

URL Format POST

https://{site}.chargebee.com/api/v1/addons/{addon_id}
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
Description about the addon to show in the hosted pages & customer portal.
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
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.quantityCharges this price for every unit of the addon. 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
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
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/v1/addons \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"
copy
curl  https://{site}.chargebee.com/api/v1/addons \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"

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, "object": "addon", "taxable": true }}, {..} ], "next_offset": "[\"77000000061\"]" }

URL Format GET

https://{site}.chargebee.com/api/v1/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
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/v1/addons/ssl \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/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, "object": "addon", "taxable": true }}

URL Format GET

https://{site}.chargebee.com/api/v1/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/v1/addons/ssl/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/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, "object": "addon", "taxable": true }}

URL Format POST

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