You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).
    Library
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

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", "enabled_in_portal": true, "id": "sms_pack", "invoice_name": "sample data pack", "name": "Sms Pack", "object": "addon", "period": 1, "period_unit": "month", "price": 200, "status": "active", "taxable": true, "type": "on_off" }

API Index URL GET

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

Addon attributes

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.
type
enumerated string
Select "On-Off" to charge a flat fee or "Quantity" for unit based charges.
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
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.
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.
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 if the addon should be taxed or not
meta_data
optional, jsonobject
A set of key-value pairs stored as additional information for the addon. Learn more.

Create an addon

Idempotency Supported
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" \
     -d type="on_off"
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" \
     -d type="on_off"

Sample Response [ JSON ]

Show more...
{"addon": { "charge_type": "recurring", "enabled_in_portal": true, "id": "sms_pack", "invoice_name": "sample data pack", "name": "Sms Pack", "object": "addon", "period": 1, "period_unit": "month", "price": 200, "status": "active", "taxable": true, "type": "on_off" }}

URL Format POST

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

Input Parameters

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.
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
type
optional, enumerated string
Select "On-Off" to charge a flat fee or "Quantity" for unit based charges.
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
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.
enabled_in_portal
optional, boolean, default=true
If enabled, customers can select this addon using the 'Change Subscription' option in the customer portal.
taxable
optional, boolean, default=true
Specifies if the addon should be taxed or not.
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 addon. Learn more.

Returns

addon
always returned
Resource object representing addon

Update an addon

Idempotency Supported

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/sub_reports \
     -u {site_api_key}:\
     -d invoice_name="sample data pack" \
     -d price=100
copy
curl  https://{site}.chargebee.com/api/v1/addons/sub_reports \
     -u {site_api_key}:\
     -d invoice_name="sample data pack" \
     -d price=100

Sample Response [ JSON ]

Show more...
{"addon": { "charge_type": "recurring", "enabled_in_portal": true, "id": "sub_reports", "invoice_name": "sample data pack", "name": "sub_Reports", "object": "addon", "period": 1, "period_unit": "month", "price": 100, "status": "active", "taxable": true, "type": "on_off" }}

URL Format POST

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

Input Parameters

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.
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
type
optional, enumerated string
Select "On-Off" to charge a flat fee or "Quantity" for unit based charges.
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
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.
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 if the addon should be taxed or not.
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 addon. Learn more.

Returns

addon
always returned
Resource object representing addon

List addons

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=3
copy
curl  https://{site}.chargebee.com/api/v1/addons \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3

Sample Response [ JSON ]

Show more...
{ "list": [ {"addon": { "charge_type": "recurring", "enabled_in_portal": true, "id": "sms_pack", "invoice_name": "sample data pack", "name": "Sms Pack", "object": "addon", "period": 1, "period_unit": "month", "price": 200, "status": "active", "taxable": true, "type": "on_off" }}, {..} ], "next_offset": "[\"133000000155\"]" }

URL Format GET

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

Input Parameters

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.

Returns

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 an addon

Retrieve a specific addon using the id.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/addons/sub_reports \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/addons/sub_reports \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"addon": { "charge_type": "recurring", "enabled_in_portal": true, "id": "sub_reports", "name": "sub_Reports", "object": "addon", "period": 1, "period_unit": "month", "price": 750, "status": "active", "taxable": true, "type": "on_off" }}

URL Format GET

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

Returns

addon
always returned
Resource object representing addon

Sample admin console URL

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

Delete an addon

Idempotency Supported

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

Sample Response [ JSON ]

Show more...
{"addon": { "charge_type": "recurring", "enabled_in_portal": true, "id": "test", "invoice_name": "sample data pack", "name": "Test", "object": "addon", "period": 1, "period_unit": "month", "price": 200, "status": "deleted", "taxable": true, "type": "on_off" }}

URL Format POST

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

Returns

addon
always returned
Resource object representing addon