When offering subscriptions of products or services, each entity that is made available for sale is represented by an “item” object. Items therefore represent the various plans, addons or charges that you offer as part of your product catalog. Non-metered
items are charged upfront in Chargebee, while metered
items are charged at the end of the billing cycle, based on usage.
There are three types of items and they’re listed and explained here. Examples for each type are provided in the table that follows.
Plan-items are items that have a recurring charge and are an essential component of any subscription. Typically, plans represent a principal or key product or service in your catalog. They are charged at recurring intervals and often have other products or services offered along with them as addons and charges.
Addon-items are items that are sold along with a plan and are charged for at recurring intervals.
Charge-items are items that are sold along with a plan but charged once (or each time) a specified event occurs. A charge can also be applied to a customer without attaching to a subscription.
To help understand each type of item better, listed below are some examples of items from different business domains:
{
"enabled_for_checkout": true,
"enabled_in_portal": true,
"id": "silver",
"is_giftable": false,
"is_shippable": false,
"item_applicability": "all",
"name": "Silver",
"object": "item",
"resource_version": 1599817249982,
"status": "active",
"type": "plan",
"updated_at": 1599817249
}
id
of the Item family that the item belongs to. Is mandatory when Product Families have been enabled. type = charge
and when the feature is enabled in Chargebee. Note: If the site-level setting is to exclude charge-items from MRR calculations, this value is always returned false
. unit
is only exposed via the API to quantity-based addons; it is however NOT exposed to quantity-based plans.
true
, the quantity is calculated from usage records. When false
, the quantity
is as determined while adding an item price to the subscription. Applicable only for items of type
plan
or addon
and when Metered Billing is enabled. The value of this attribute cannot be changed. metered
. This value overrides the one set at the site level. item_applicability
is restricted
. Other details of attaching items can be specified using the Create or Update an attached item API.# create a plan item curl https://{site}.chargebee.com/api/v2/items \ -u {site_api_key}:\ -d id="silver" \ -d name="Silver" \ -d type="PLAN" \ -d item_applicability="ALL"
# create an addon item curl https://{site}.chargebee.com/api/v2/items \ -u {site_api_key}:\ -d id="ssl" \ -d name="ssl" \ -d type="ADDON"
# create a plan item with restricted applicable addon item curl https://{site}.chargebee.com/api/v2/items \ -u {site_api_key}:\ -d id="gold" \ -d name="Gold" \ -d type="PLAN" \ -d item_applicability="RESTRICTED" \ -d applicable_items[0]="day-pass"
id
of the Item family that the item belongs to. Is mandatory when Product Families have been enabled. unit
is only exposed via the API to quantity-based addons; it is however NOT exposed to quantity-based plans.
type = charge
and when the feature is enabled in Chargebee. Note: If the site-level setting is to exclude charge-items from MRR calculations, this value is always returned false
. true
, the quantity is calculated from usage records. When false
, the quantity
is as determined while adding an item price to the subscription. Applicable only for items of type
plan
or addon
and when Metered Billing is enabled. The value of this attribute cannot be changed. metered
. This value overrides the one set at the site level. . curl https://{site}.chargebee.com/api/v2/items/cbdemo_additionaluser \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/items/basic \ -u {site_api_key}:\ -d description="basic plan" \ -d enabled_for_checkout=false \ -d enabled_in_portal=false
id
of the Item family that the item belongs to. Is mandatory when Product Families have been enabled. unit
is only exposed via the API to quantity-based addons; it is however NOT exposed to quantity-based plans.
type = charge
and when the feature is enabled in Chargebee. Note: If the site-level setting is to exclude charge-items from MRR calculations, this value is always returned false
. curl https://{site}.chargebee.com/api/v2/items \ -G \ -u {site_api_key}:\ --data-urlencode limit=2
true
, the quantity is calculated from usage records. When false
, the quantity
is as determined while adding an item price to the subscription. Applicable only for items of type
plan
or addon
and when Metered Billing is enabled. The value of this attribute cannot be changed. Possible values are : true, false metered
. This value overrides the one set at the site level. . Possible values are : sum_of_usages, last_usage, max_usage status
as deleted. This is not allowed if there are active
or archived
item prices under the item. Once deleted, the id and name of the item can be reused.curl https://{site}.chargebee.com/api/v2/items/delete-sample/delete \ -X POST \ -u {site_api_key}: