Addons

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

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=2000
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

charge_type

enumerated string, default=recurring
Type of charge

Possible values are

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

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

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

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

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=2000
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

charge_type

enumerated string, default=recurring
Type of charge

Possible values are

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

unit

status

enumerated string, default=active
Status of the addon

Possible values are

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

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

Sample Request

Only for Java

copy full code

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

copy

Click to Copy

Sample Response [ JSON ]

{
    "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

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=2000
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

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

type[]

optional, enumerated string
Select "On-Off" to charge a flat fee or "Quantity" for unit based charges.

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

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

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

Sample Request

Only for Java

copy full code

Click to Copy

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 ]

{
    "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}

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=2000
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

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

type[]

optional, enumerated string
Select "On-Off" to charge a flat fee or "Quantity" for unit based charges.

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

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

addon

always returned
Resource object representing addon

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

Sample Request

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v1/addons \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3

copy

Click to Copy

Sample Response [ JSON ]

{
    "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

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

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

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

Sample Response [ JSON ]

{
    "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}

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

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

Sample Response [ JSON ]

{
    "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

addon

always returned
Resource object representing addon

Sample addon [ JSON ]

API Index URL GET

Model Class

Addon attributes

Consent Fields for Addon

Custom Fields for Addon

Create an addon ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Update an addon ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List addons ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve an addon ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Delete an addon ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL