Features

API Version

Product Catalog

Library

Subscriptions are created in Chargebee using items. Items represent the products or services that you offer to your customers. Items often differ in the number of product features that are available to them. The Features API helps you define the various features offered as part of your product line. It also defines the entitlements that items and subscriptions can have towards said features.

Note

The maximum number of features a site can have is 400.

Features of this API

The Features API enables you to:

Define the set of features provided by your product.
Specify the entitlements that items have towards said features.
For a given subscription, modify the entitlements inherited from items in the subscription.
Offer additional feature entitlements to subscriptions than those inherited from items in the subscription.
Serve as a source of truth to your provisioning systems for subscription entitlements.
Use entitlement information to understand which features drive value and revenue.

See also

Sample feature [ JSON ]

{
    "feature": {
        "description": "Integration of Chargebee with Quickbooks",
        "id": "fea-4c163c85-f873-46d4-a268-5a80ddf40971",
        "levels": [],
        "name": "Quickbooks Integration_123",
        "object": "feature",
        "status": "draft",
        "type": "switch"
    }
}

API Index URL

https://{site}.chargebee.com/api/v2/features

id

string, max chars=50
A unique and immutable identifier for the feature. You can set it yourself, in which case it is recommended that a human-readable format (or slug) be used. For example, number-of-users-ccjht01. When not provided, a random value is automatically set.

name

string, max chars=50
A case-sensitive unique name for the feature. For example: user license, data storage, Salesforce Integration, devices, UHD Streaming, and so on.
Note: This name is not displayed on any customer-facing documents or pages such as invoice PDFs or hosted pages. However, in the future, it is likely to be introduced on the Self-Serve Portal.

description

optional, string, max chars=500
A brief description of the feature. For example: Access to 10TB cloud storage.

status

optional, enumerated string
The current status of the feature.

Possible values are

type

optional, enumerated string
The type of feature.

Possible values are

unit

optional, string, max chars=50
For features of type quantity or range, this specifies the unit of measure. The value is expected in the singular form and when used by the system, it is pluralized automatically as needed. For example, for a feature such as user licenses, the unit can be license.

resource_version

optional, long
The version number of this resource. For every change made to the resource, resource_version is updated with a new timestamp in milliseconds.

updated_at

optional, timestamp(UTC) in seconds
The version number of this resource. For every change made to the resource, resource_version is updated with a new timestamp in milliseconds.

created_at

timestamp(UTC) in seconds
When the feature was created.

levels
Show attributes [+]

optional, list of level
An ordered list of entitlement levels available for the feature. This is only applicable when type is other than switch.
Note: When the type of the feature is switch, this is not applicable. This is because any given entity can be either fully entitled to a switch feature or not entitled at all; there are no intermediate entitlement levels.

Level attributes

name

optional, string, max chars=50
A case-sensitive display name for the entitlement level. Provide a name that helps you clearly identify the entitlement level. For example: a feature such as Email Support can have entitlement levels named as All weekdays, All days, 40 hours per week and so on. When not provided for feature.type quantity or range, this name is auto-generated as the space-separated concatenation of levels[].value and the pluralized version of unit. For example, if levels[].value is 20 and unit is user, then levels[].name becomes 20 users.

value

string, max chars=50
The value denoting the entitlement level granted.

When type is quantity: this attribute denotes the quantity of units of the feature for this entitlement level. For example, a feature such as number of users can have levels[].value as 5, 20, 50, and 100. levels[].is_unlimited is used to set the entitlement level to “unlimited”.
When type is range: there can be be only two elements in the levels[] array; one corresponding to the minimum value (levels[0]) and the other to the maximum value (levels[1]) of the range of possible entitlement levels. For example, a feature such as number of users may have levels[0].value = 5 and levels[1].value = 50000. When the upper limit is “unlimited”, then levels[1].value is not set and levels[1].is_unlimited is true.
When type is custom: this attribute denotes the value of this custom entitlement level. For example, a feature Email Support can have levels[].value as one of say, 24×7 and 24×5.

level

integer
This attribute represents the order of the entitlement levels from lowest to highest.

When type is quantity or custom: The lowest entitlement level has the value 0, the next higher level has the value 1, followed by 2, and so on.
When type is range: This attribute is 0 for the minimum value and 1 for the maximum value in the range.

When not defined, it is assumed as the index of the levels[] array.

is_unlimited

boolean
When type is quantity or range, this attribute indicates whether the entitlement level corresponds to unlimited units of the feature. Possible values:

true: The entitlement level corresponds to unlimited units of the feature. levels[].value is ignored for this level. This can only be set for the level that has the highest value for levels[].level.
false: The entitlement level does not correspond to unlimited units of the feature.

id

name

description

optional, string, max chars=500
A brief description of the feature. For example: Access to 10TB cloud storage.

status

optional, enumerated string
The current status of the feature.

Possible values are

type

optional, enumerated string
The type of feature.

Possible values are

unit

resource_version

optional, long
The version number of this resource. For every change made to the resource, resource_version is updated with a new timestamp in milliseconds.

updated_at

optional, timestamp(UTC) in seconds
The version number of this resource. For every change made to the resource, resource_version is updated with a new timestamp in milliseconds.

created_at

timestamp(UTC) in seconds
When the feature was created.

levels

Try in API Explorer

Retrieves a list of features meeting all the conditions specified in the filter parameters.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/features \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "feature": {
                "description": "Integration of Chargebee with Quickbooks",
                "id": "fea-4c163c85-f873-46d4-a268-5a80ddf40971",
                "levels": [],
                "name": "Quickbooks Integration_123",
                "object": "feature",
                "status": "draft",
                "type": "switch"
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/features

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.

Filter Params

For operator usages, see the Pagination and Filtering section.

name[<operator>]

optional, string filter
A case-sensitive unique name for the feature. For example: user license, data storage, Salesforce Integration, devices, UHD Streaming, and so on.
Note: This name is not displayed on any customer-facing documents or pages such as invoice PDFs or hosted pages. However, in the future, it is likely to be introduced on the Self-Serve Portal.
Supported operators : is, is_not, starts_with, in, not_in

Example → name[is] = "User licenses"

id[<operator>]

optional, string filter
A unique and immutable identifier for the feature. You can set it yourself, in which case it is recommended that a human-readable format (or slug) be used. For example, number-of-users-ccjht01. When not provided, a random value is automatically set.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "fea-user-licenses"

status[<operator>]

optional, enumerated string filter
The current status of the feature. Possible values are : active, archived, draft
Supported operators : is, is_not, in, not_in

Example → status[is] = "active"

type[<operator>]

optional, enumerated string filter
The type of feature. Possible values are : switch, custom, quantity, range
Supported operators : is, is_not, in, not_in

Example → type[is] = "boolean"

feature

always returned
Resource object representing feature

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

Try in API Explorer

Creates a new feature.

Sample Request

Try in API Explorer

Only for Java

Only for Java

Only for Java

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/features \
     -u {site_api_key}:\
     -d name="Quickbooks Integration_123" \
     -d type="SWITCH" \
     -d description="Integration of Chargebee with Quickbooks"

curl  https://{site}.chargebee.com/api/v2/features \
     -u {site_api_key}:\
     -d name="Phone Support" \
     -d type="CUSTOM" \
     -d "levels[level][0]"=0 \
     -d "levels[value][0]"="24 * 5" \
     -d "levels[name][0]"="24 * 5" \
     -d "levels[level][1]"=1 \
     -d "levels[value][1]"="24 * 7" \
     -d "levels[name][1]"="24 * 7"

curl  https://{site}.chargebee.com/api/v2/features \
     -u {site_api_key}:\
     -d name="User Licenses" \
     -d type="QUANTITY" \
     -d description="Maximum user licenses allowed" \
     -d "levels[level][0]"=0 \
     -d "levels[value][0]"="5" \
     -d "levels[name][0]"="5 Users" \
     -d "levels[level][1]"=1 \
     -d "levels[value][1]"="10" \
     -d "levels[name][1]"="10 Users" \
     -d "levels[level][2]"=2 \
     -d "levels[value][2]"="Unlimited" \
     -d "levels[name][2]"="Unlimited Users" \
     -d "levels[is_unlimited][2]"=true

curl  https://{site}.chargebee.com/api/v2/features \
     -u {site_api_key}:\
     -d name="API call limit" \
     -d type="RANGE" \
     -d description="API call limit" \
     -d "levels[level][0]"=0 \
     -d "levels[value][0]"="5" \
     -d "levels[name][0]"="5 calls/month" \
     -d "levels[level][1]"=1 \
     -d "levels[value][1]"="100" \
     -d "levels[name][1]"="100 calls/month"

copy

Click to Copy

Create a switch feature

Create a custom type feature

Create a quantity type feature

Create a range type feature

200:

STATUS

Sample Response [ JSON ]

{
    "feature": {
        "description": "Integration of Chargebee with Quickbooks",
        "id": "fea-0e400372-75e0-432a-ae30-82f796a5b7e6",
        "levels": [],
        "name": "Quickbooks Integration_123",
        "object": "feature",
        "status": "draft",
        "type": "switch"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/features

id[]

optional, string, max chars=50
A unique and immutable identifier for the feature. You can set it yourself, in which case it is recommended that a human-readable format (or slug) be used. For example, number-of-users-ccjht01. When not provided, a random value is automatically set.

name[]

required, string, max chars=50
A case-sensitive unique name for the feature. For example: user license, data storage, Salesforce Integration, devices, UHD Streaming, and so on.
Note: This name is not displayed on any customer-facing documents or pages such as invoice PDFs or hosted pages. However, in the future, it is likely to be introduced on the Self-Serve Portal.

description[]

optional, string, max chars=500
A brief description of the feature. For example: Access to 10TB cloud storage.

type[]

optional, enumerated string
The type of feature.

Possible values are

status[]

optional, enumerated string
The current status of the feature.

Possible values are

unit[]

levels

Parameters for levels. Multiple levels can be passed by specifying unique indices.
pass parameters as levels[<param name>][<idx:0..n>]

levels[name][0..n]

optional, string, max chars=50

levels[value][0..n]

optional, string, max chars=50

levels[is_unlimited][0..n]

optional, boolean

levels[level][0..n]

optional, integer

feature

always returned
Resource object representing feature

Try in API Explorer

Updates a specific feature.

Note

The list of objects levels[] provided as part of this operation fully replaces the existing list of objects levels[] of the feature.

Considerations when modifying `levels`

This section describes validations that are performed by Chargebee when modifying the levels list of objects for the feature, using this operation.

Adding `levels`

Adding a new object to the levels[] list is allowed if and only if the feature type is quantity or custom

Removing `levels`

Removing an existing object in the levels[] list is not allowed if the value for that object is currently mapped to one or more item_entitlements or subscription_entitlements.

Reordering `levels`

Note

The validation described in this section is only applicable for features of type custom

If any of levels[].value are currently mapped to item_entitlements or subscription_entitlements, then the relative order of the corresponding levels[].level must be preserved when invoking this operation.

For example, consider that the levels[] list is currently in the state shown below. (For brevity, only the value and level key are shown here and the JSONs have been compacted.)


    {
        "levels":[{
            "value":"email-basic",
            "level":0
        },{
            "value":"email-rise",
            "level":1
        },{
            "value":"email-advanced",
            "level":2
        },{
            "value":"email-pro",
            "level":3
        },{
            "value":"email-scale",
            "level":4
        }]
    }

Now consider that email-rise, email-advanced, and email-pro have already been mapped to item_entitlements or subscription_entitlements. As seen in the above object, the relative order of levels[].level is such that email-rise < email-advanced < email-pro.

Invoking this API to change levels[] to the state below is allowed since the relative order of level corresponding to email-rise, email-advanced, and email-pro has been preserved.


    {
        "levels":[{
            "value":"email-basic",
            "level":0
        },{
            "value":"email-rise",
            "level":1
        },{
            "value":"email-scale",
            "level":2
        },{
            "value":"email-advanced",
            "level":3
        },{
            "value":"email-pro",
            "level":4
        }]
    }

However, changing levels[] to the state shown below is not permissible because the level of email-advanced is provided as greater than the level of email-pro, thereby disrupting the original order.


    {
        "levels":[{
            "value":"email-basic",
            "level":0
        },{
            "value":"email-rise",
            "level":1
        },{
            "value":"email-pro",
            "level":2
        },{
            "value":"email-advanced",
            "level":3
        },{
            "value":"email-scale",
            "level":4
        }]
    }

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/features/fea-a5d1f7de-c58c-45da-a08b-6934e3ab3ede \
     -u {site_api_key}:\
     -d name="User Licenses (updated name)" \
     -d description="Maximum number of user licenses allowed" \
     -d "levels[level][0]"=0 \
     -d "levels[value][0]"="25" \
     -d "levels[name][0]"="25 Users" \
     -d "levels[level][1]"=1 \
     -d "levels[value][1]"="100" \
     -d "levels[name][1]"="100 Users" \
     -d "levels[level][2]"=2 \
     -d "levels[value][2]"="Unlimited" \
     -d "levels[name][2]"="Unlimited Users" \
     -d "levels[is_unlimited][2]"=true

copy

Click to Copy

Update a quantity type feature

200:

STATUS

Sample Response [ JSON ]

{
    "feature": {
        "description": "Maximum number of user licenses allowed",
        "id": "fea-a5d1f7de-c58c-45da-a08b-6934e3ab3ede",
        "levels": [
            {
                "is_unlimited": false,
                "level": 0,
                "name": "25 Users",
                "value": "25"
            },
            {..}
        ],
        "name": "User Licenses (updated name)",
        "object": "feature",
        "status": "active",
        "type": "quantity"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/features/{feature-id}

name[]

optional, string, max chars=50
A case-sensitive unique name for the feature. For example: user license, data storage, Salesforce Integration, devices, UHD Streaming, and so on.
Note: This name is not displayed on any customer-facing documents or pages such as invoice PDFs or hosted pages. However, in the future, it is likely to be introduced on the Self-Serve Portal.

description[]

optional, string, max chars=500
A brief description of the feature. For example: Access to 10TB cloud storage.

status[]

optional, enumerated string
The current status of the feature.

Possible values are

unit[]

levels

Parameters for levels. Multiple levels can be passed by specifying unique indices.
pass parameters as levels[<param name>][<idx:0..n>]

levels[name][0..n]

optional, string, max chars=50

levels[value][0..n]

optional, string, max chars=50

levels[is_unlimited][0..n]

optional, boolean

levels[level][0..n]

optional, integer

feature

always returned
Resource object representing feature

Try in API Explorer

Retrieve a specific feature using its ID.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/features/fea-user-licenes \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "feature": {
        "id": "fea-custom-id-121",
        "name": "User Licenses",
        "description": "Maximum Available User Licenses",
        "status": "draft",
        "type": "range",
        "levels": [
            {
                "name": "3 Users",
                "value": "3",
                "is_unlimited": false,
                "level": 1
            },
            {..}
        ],
        "object": "feature"
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/features/{feature-id}

feature

always returned
Resource object representing feature

Try in API Explorer

Deletes a feature. Any entitlements and subscription entitlements defined for the feature are also removed. This action is not permissible when the status of the feature is active.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/features/fea-d49b2371-572b-439d-993d-04b8135194c3/delete \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "feature": {
        "description": "Integration of Chargebee with Quickbooks",
        "id": "fea-d49b2371-572b-439d-993d-04b8135194c3",
        "levels": [],
        "name": "Quickbooks Integration_123",
        "object": "feature",
        "status": "draft",
        "type": "switch"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/features/{feature-id}/delete

feature

always returned
Resource object representing feature

Try in API Explorer

Activates a draft feature so that any entitlements or subscription entitlements defined towards it take effect immediately. This operation changes the status of the feature to active. The feature status must be draft when calling this endpoint.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/features/fea-8f2fb6c8-d582-435a-9d92-b3e04ec7f40e/activate_command \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "feature": {
        "description": "Maximum user licenses allowed",
        "id": "fea-8f2fb6c8-d582-435a-9d92-b3e04ec7f40e",
        "levels": [
            {
                "is_unlimited": false,
                "level": 0,
                "name": "5 Users",
                "value": "5"
            },
            {..}
        ],
        "name": "User Licenses af",
        "object": "feature",
        "status": "active",
        "type": "quantity"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/features/{feature-id}/activate_command

feature

always returned
Resource object representing feature

Try in API Explorer

Archives an active feature so that no new entitlements or subscription entitlements can be created towards the feature. Any pre-existing item or subscription entitlements from the time that the feature was active remain effective. This operation changes the status of the feature to archived. The feature status must be active when calling this endpoint.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/features/fea-c3c68438-9f26-4a88-b2cb-88428a8d85f5/archive_command \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "feature": {
        "description": "Maximum user licenses allowed",
        "id": "fea-c3c68438-9f26-4a88-b2cb-88428a8d85f5",
        "levels": [
            {
                "is_unlimited": false,
                "level": 0,
                "name": "5 Users",
                "value": "5"
            },
            {..}
        ],
        "name": "User Licenses arf",
        "object": "feature",
        "status": "archived",
        "type": "quantity"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/features/{feature-id}/archive_command

feature

always returned
Resource object representing feature

Try in API Explorer

Reactivates an archived feature so that new entitlements or subscription entitlements can be created towards the feature. This operation changes the status of the feature to active. The feature status must be archived when calling this endpoint.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/features/fea-a2dbb732-c54d-4a96-aaa3-b8c0b362e578/reactivate_command \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "feature": {
        "description": "Maximum user licenses allowed",
        "id": "fea-a2dbb732-c54d-4a96-aaa3-b8c0b362e578",
        "levels": [
            {
                "is_unlimited": false,
                "level": 0,
                "name": "5 Users",
                "value": "5"
            },
            {..}
        ],
        "name": "User Licenses rf",
        "object": "feature",
        "status": "active",
        "type": "quantity"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/features/{feature-id}/reactivate_command

feature

always returned
Resource object representing feature

Features of this API

Sample feature [ JSON ]

API Index URL

Model Class

Feature attributes

Consent Fields for Feature

Custom Fields for Feature

List features ¶

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

Create a feature ¶

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 a feature ¶

Considerations when modifying levels

Adding levels

Removing levels

Reordering levels

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

Retrieve a feature ¶

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 a feature ¶

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

Activate a feature ¶

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

Archive a feature ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Considerations when modifying `levels`

Adding `levels`

Removing `levels`

Reordering `levels`