API Version
Product Catalog
Library

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

Model Class

id
string, max chars=100
A unique ID for your system to identify the addon.
name
string, max chars=100
The display name used in web interface for identifying the addon.
invoice_name
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
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
Show all values[+]
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.
Show all values[+]
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)
Show all values[+]
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 subscriptionsarchivedNo 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.
Show all values[+]
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.
proration_type
optional, enumerated string, default=site_default
null
Possible values are
site_defaultpartial_termfull_term
Show all values[+]
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.
id id
string, max chars=100
A unique ID for your system to identify the addon.
name name
string, max chars=100
The display name used in web interface for identifying the addon.
invoice_name invoice_name
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
description 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 type
enumerated string
Select "On-Off" to charge a flat fee or "Quantity" for unit based charges.
charge_type charge_type
enumerated string, default=recurring
Type of charge
price 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 period
optional, integer, min=1
Applicable only for recurring-addons. Along with 'period_unit' decides the term-price of this addon.
period_unit period_unit
enumerated string
Applicable only for recurring-addons. Along with 'period' decides the term-price of this addon
unit 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 status
enumerated string, default=active
Status of the addon
archived_at archived_at
optional, timestamp(UTC) in seconds
Time at which the plan was moved to archived status.
enabled_in_portal enabled_in_portal
boolean, default=true
If enabled, customers can select this addon using the 'Change Subscription' option in the customer portal.
proration_type proration_type
optional, enumerated string, default=site_default
null
invoice_notes 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 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 a new addon.

Notes

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
Click to Copy

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

Method

id[]
required, string, max chars=100
A unique ID for your system to identify the addon.
name[]
required, string, max chars=100
The display name used in web interface for identifying the addon.
invoice_name[]
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
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.
Show all values[+]
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)
Show all values[+]
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
Show all values[+]
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.
proration_type[]
optional, enumerated string, default=site_default
null
Possible values are
site_defaultpartial_termfull_term
Show all values[+]
addon addon
always returned
Resource object representing addon

Sample admin console URL

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

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

Notes

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
Click to Copy

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}

Method

name[]
optional, string, max chars=100
The display name used in web interface for identifying the addon.
invoice_name[]
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
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, 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.
Show all values[+]
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)
Show all values[+]
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
Show all values[+]
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.
proration_type[]
optional, enumerated string, default=site_default
null
Possible values are
site_defaultpartial_termfull_term
Show all values[+]
addon addon
always returned
Resource object representing addon

Sample admin console URL

https://{site}.chargebee.com/admin-console/addons/123x
List the addons. This returns all your current active and archived addons.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/addons \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3
copy
Click to Copy

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

Method

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.
addon addon
always returned
Resource object representing addon
next_offset 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`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/addons/123x
Retrieve a specific addon using the id.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/addons/sub_reports \
     -u {site_api_key}:
copy
Click to Copy

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}

Method

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

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/addons/test/delete \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

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

Method

addon addon
always returned
Resource object representing addon

Sample admin console URL

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