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.
Types of Items
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 or Plans
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 or Addons
Addon-items are items that are sold along with a plan and are charged for at recurring intervals.
Charge-items or Charges
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.
Examples
To help understand each type of item better, listed below are some examples of items from different business domains:
Non-Metered (SaaS)
- Item Family: A project management solution.
- Plans:
- A “basic” plan offering a small set of features.
- A “business” plan offering a larger set of features.
- Addons:
- An analytics plugin that is available only with the “business” plan.
- A reporting plugin, available with both the above plans.
- Charges:
- Implementation charges.
- Trial charges.
Non-Metered (E-commerce)
- Item Family: A printed news magazine.
- Plans:
- Periodic issues of the magazine.
- Periodic issues of the magazine, with digital content.
- Addons:
- Supplementary online content.
- Access to a year’s worth of back issues.
- Searchable access to all back issues.
- Charges:
- Special edition books that are published every so often.
Metered
- Item Family: SMS delivery services.
- Plans:
- A basic plan of up to 100K messages @ $0.03 per message.
- A volume plan of 2M messages @ $0.01 per message.
- Addons:
- An addon of 50K MMS messages @ $0.1 per message.
- Instant messaging.
- Charges:
- Automated Metered Billing is not applicable for charges.
Sample item [ JSON ]
{
"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
}
API Index URL GET
https://{site}.chargebee.com/api/v2/items
string, max chars=100
The identifier for the item. It is unique and immutable.
string, max chars=50
A unique display name for the item. This is visible only in Chargebee and not to customers.
optional, string, max chars=100
A unique display name for the item.
optional, string, max chars=500
Description of the item. This is visible only in Chargebee and not to customers.
optional, enumerated stringThe status of the item.
Possible values are
activeThe item can be used to create new item prices.archivedThe item is no longer active and no new item prices can be created.deletedIndicates that the item has been deleted. The id
and name
can be reused. Deleted items can be retrieved using List items.
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.
optional, timestamp(UTC) in seconds
Timestamp indicating when the item was last updated.
optional, string, max chars=100The
id
of the
Item family that the item belongs to. Is mandatory when
Product Families have been enabled.
enumerated stringThe type of the item.
Possible values are
planAn essential component of a subscription. Every subscription has exactly one plan. It has a recurring charge and its period defines the billing period of the subscription.addonA recurring component that can be added to a subscription in addition to its plan.chargeA non-recurring component that can be added to a subscription in addition to its plan. An charge can also be applied to a customer directly without being applied to a subscription.
optional, boolean, default=false
Indicates that the item is a physical product. If Orders are enabled in Chargebee, subscriptions created for this item will have orders associated with them.
boolean, default=false
Specifies if gift subscriptions can be created for this item.
optional, string, max chars=500
If enabled_for_checkout
, then the URL to be redirected to once the checkout is complete. This attribute is only available for plan-items.
boolean, default=true
Allow the plan to subscribed to via Checkout. Applies only for plan-items.
Note: Only the in-app version of Checkout is supported for Product Catalog v2.
optional, boolean
The item is included in MRR calculations for your site. This attribute is only applicable for items of 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
.
enumerated string, default=allIndicates which addon-items and charge-items can be applied to the item. Only meant for plan-items. Other details of attaching items such as whether to attach as a mandatory item or to attach on a certain event, can be specified using the
Create or
Update an attached item API.
Possible values are
allall addon-items and charge-items are applicable to this plan-item.restrictedonly the addon-items or charge-items provided in applicable_items
can be applied to this plan-item.
optional, string, max chars=500
The URL to redirect to once the gift has been claimed by the receiver.
optional, string, max chars=30The unit of measure for a quantity-based item. This is displayed on the Chargebee UI and on customer facing documents/pages. The latter includes
hosted pages,
invoices and
quotes. Examples follow:
- “user“ for a cloud-collaboration platform.
- “GB“ for a data service.
- “issue“ for a magazine.
Note: unit
is only exposed via the API to quantity-based addons; it is however NOT exposed to quantity-based plans.
boolean, default=falseSpecifies whether the item undergoes metered billing. When
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.
optional, enumerated stringHow the quantity is calculated from usage data for the item prices belonging to this item. Only applicable when the item is
metered
. This value overrides the one
set at the site level.
Possible values are
sum_of_usagesthe net quantity is the sum of the quantity
of all usages for the current term.last_usagefrom among the usage records for the item price with usage_date
within the relevant billing period, the quantity
of the usage record with the most recent usage_date
is taken as the net quantity consumed.max_usagefrom among the usage records for the item price with usage_date
within the relevant billing period, the quantity
of the usage record with the maximum value is taken as the net quantity consumed.
optional, timestamp(UTC) in seconds
Timestamp indicating when this item was archived.
optional, enumerated stringThe subscription channel this object originated from and is maintained in.
Possible values are
webThe object was created (and is maintained) for the web channel directly in Chargebee via API or UI.app_storeThe object data is synchronized with data from in-app subscription(s) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.play_storeThe object data is synchronized with data from in-app subscription(s) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.
In-App Subscriptions is currently in early access. Contact
eap@chargebee.com for more information.
.
optional, jsonobjectA set of key-value pairs stored as additional information for the item.
Learn more.
optional, list of applicable_itemThe list of addons and charges that are allowed to be applied to the plan. This attribute is applicable only for plan-items and that too when
item_applicability
is
restricted
. Other details of attaching items can be specified using the
Create or
Update an attached item API.
Applicable item attributes
optional, string, max chars=100
Id of the addon-item or plan-item that can be applied to the plan-item.
Creates a new item.
Sample Request
# create a plan item
curl https://{site}.chargebee.com/api/v2/items \
-X POST \
-u {site_api_key}:\
-d id="silver" \
-d name="Silver" \
-d type="plan" \
-d item_applicability="all"
copy
# create a plan item
curl https://{site}.chargebee.com/api/v2/items \
-X POST \
-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 \
-X POST \
-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 \
-X POST \
-u {site_api_key}:\
-d id="gold" \
-d name="Gold" \
-d type="plan" \
-d item_applicability="restricted" \
-d applicable_items[0]="day-pass"
Sample Response [ JSON ]
Show more...
{"item": {
"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
}}
Show more...
{"item": {
"enabled_for_checkout": true,
"enabled_in_portal": true,
"id": "ssl",
"is_giftable": false,
"is_shippable": false,
"name": "ssl",
"object": "item",
"resource_version": 1599817250096,
"status": "active",
"type": "addon",
"updated_at": 1599817250
}}
Show more...
{"item": {
"applicable_items": [
{"id": "day-pass"},
{..}
],
"enabled_for_checkout": true,
"enabled_in_portal": true,
"id": "gold",
"is_giftable": false,
"is_shippable": false,
"item_applicability": "restricted",
"name": "Gold",
"object": "item",
"resource_version": 1599817250235,
"status": "active",
"type": "plan",
"updated_at": 1599817250
}}
URL Format POST
https://{site}.chargebee.com/api/v2/items
required, string, max chars=100
The identifier for the item. Must be unique and is immutable once set.
required, string, max chars=50
A unique display name for the item. Must be unique. This is visible only in Chargebee and not to customers.
required, enumerated stringThe type of the item.
Possible values are
planAn essential component of a subscription. Every subscription has exactly one plan. It has a recurring charge and its period defines the billing period of the subscription.addonA recurring component that can be added to a subscription in addition to its plan.chargeA non-recurring component that can be added to a subscription in addition to its plan. An charge can also be applied to a customer directly without being applied to a subscription.
optional, string, max chars=500
Description of the item. This is visible only in Chargebee and not to customers.
required, string, max chars=100The
id
of the
Item family that the item belongs to. Is mandatory when
Product Families have been enabled.
optional, boolean, default=false
Specifies if gift subscriptions can be created for this item.
optional, boolean, default=false
Indicates that the item is a physical product. If Orders are enabled in Chargebee, subscriptions created for this item will have orders associated with them.
optional, string, max chars=100
A unique display name for the item.
optional, boolean, default=trueAllow customers to change their subscription to this plan via the
Self-Serve Portal. Applies only for plan-items. This requires the Portal configuration to
allow changing subscriptions. Only the in-app version of the Portal is supported for Product Catalog v2.
optional, string, max chars=500
If enabled_for_checkout
, then the URL to be redirected to once the checkout is complete. This attribute is only available for plan-items.
optional, boolean, default=true
Allow the plan to subscribed to via Checkout. Applies only for plan-items.
Note: Only the in-app version of Checkout is supported for Product Catalog v2.
optional, enumerated string, default=allIndicates which addon-items and charge-items can be applied to the item. Only possible for plan-items. Other details of attaching items such as whether to attach as a mandatory item or to attach on a certain event, can be specified using the
Create or
Update an attached item API.
Possible values are
allall addon-items and charge-items are applicable to this plan-item.restrictedonly the addon-items or charge-items provided in applicable_items
can be applied to this plan-item.
optional, list of stringThe list of ids of addon-items and charge-items that can be applied to the plan-item. This parameter can be provided only for plan-items and that too when item_applicability is restricted. Other details of attaching items can be specified using the
Create or
Update an attached item API.
optional, string, max chars=30The unit of measure for a quantity-based item. This is displayed on the Chargebee UI and on customer facing documents/pages. The latter includes
hosted pages,
invoices and
quotes. Examples follow:
- “user“ for a cloud-collaboration platform.
- “GB“ for a data service.
- “issue“ for a magazine.
Note: unit
is only exposed via the API to quantity-based addons; it is however NOT exposed to quantity-based plans.
.
optional, string, max chars=500
The URL to redirect to once the gift has been claimed by the receiver.
optional, boolean
The item is included in MRR calculations for your site. This attribute is only applicable for items of 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
.
optional, boolean, default=falseSpecifies whether the item undergoes metered billing. When
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.
optional, enumerated stringHow the quantity is calculated from usage data for the item prices belonging to this item. Only applicable when the item is
metered
. This value overrides the one
set at the site level. .
Possible values are
sum_of_usagesthe net quantity is the sum of the quantity
of all usages for the current term.last_usagefrom among the usage records for the item price with usage_date
within the relevant billing period, the quantity
of the usage record with the most recent usage_date
is taken as the net quantity consumed.max_usagefrom among the usage records for the item price with usage_date
within the relevant billing period, the quantity
of the usage record with the maximum value is taken as the net quantity consumed.
optional, jsonobjectA set of key-value pairs stored as additional information for the item.
Learn more.
always returned
Resource object representing item
Retrieve an item resource.
Sample Request
curl https://{site}.chargebee.com/api/v2/items/cbdemo_additionaluser \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/items/cbdemo_additionaluser \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{"item": {
"enabled_for_checkout": true,
"enabled_in_portal": true,
"id": "cbdemo_additionaluser",
"is_giftable": false,
"is_shippable": false,
"name": "CbDemo Additional User",
"object": "item",
"resource_version": 1599817250735,
"status": "active",
"type": "addon",
"updated_at": 1599817250
}}
URL Format GET
https://{site}.chargebee.com/api/v2/items/{item_id}
always returned
Resource object representing item
Updates an item with the changes specified. Unspecified item parameters are not modified.
Sample Request
curl https://{site}.chargebee.com/api/v2/items/basic \
-X POST \
-u {site_api_key}:\
-d description="basic plan" \
-d enabled_for_checkout="false" \
-d enabled_in_portal="false"
copy
curl https://{site}.chargebee.com/api/v2/items/basic \
-X POST \
-u {site_api_key}:\
-d description="basic plan" \
-d enabled_for_checkout="false" \
-d enabled_in_portal="false"
Sample Response [ JSON ]
Show more...
{"item": {
"description": "basic plan",
"enabled_for_checkout": false,
"enabled_in_portal": false,
"id": "basic",
"is_giftable": false,
"is_shippable": false,
"item_applicability": "all",
"name": "Basic",
"object": "item",
"resource_version": 1599817250886,
"status": "active",
"type": "plan",
"updated_at": 1599817250
}}
URL Format POST
https://{site}.chargebee.com/api/v2/items/{item_id}
optional, string, max chars=50
The display name for the item. Must be unique. This is visible only in Chargebee and not to customers.
optional, string, max chars=500
Description of the item. This is visible only in Chargebee and not to customers.
optional, boolean
Indicates that the item is a physical product. If Orders are enabled in Chargebee, subscriptions created for this item will have orders associated with them.
optional, string, max chars=100
A unique display name for the item.
optional, string, max chars=100The
id
of the
Item family that the item belongs to. Is mandatory when
Product Families have been enabled.
optional, string, max chars=500
If enabled_for_checkout
, then the URL to be redirected to once the checkout is complete. This parameter is only meant for plan-items.
optional, boolean
Allow the plan to subscribed to via Checkout. Applies only for plan-items.
Note: Only the in-app version of Checkout is supported for Product Catalog v2.
optional, enumerated stringIndicates which addon-items and charge-items can be applied to the item. Only possible for plan-items. Other details of attaching items such as whether to attach as a mandatory item or to attach on a certain event, can be specified using the
Create or
Update an attached item API.
Possible values are
allall addon-items and charge-items are applicable to this plan-item.restrictedonly the addon-items or charge-items provided in applicable_items
can be applied to this plan-item.
optional, list of stringThe list of ids of addon-items and charge-items that can be applied to the plan-item. This parameter can be provided only for plan-items and that too when item_applicability is restricted. Other details of attaching items can be specified using the
Create or
Update an attached item API.
optional, string, max chars=30The unit of measure for a quantity-based item. This is displayed on the Chargebee UI and on customer facing documents/pages. The latter includes
hosted pages,
invoices and
quotes. Examples follow:
- “user“ for a cloud-collaboration platform.
- “GB“ for a data service.
- “issue“ for a magazine.
Note: unit
is only exposed via the API to quantity-based addons; it is however NOT exposed to quantity-based plans.
.
optional, string, max chars=500
The URL to redirect to once the gift has been claimed by the receiver.
optional, jsonobjectA set of key-value pairs stored as additional information for the item.
Learn more.
optional, boolean
The item is included in MRR calculations for your site. This attribute is only applicable for items of 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
.
optional, enumerated stringThe status of the item.
Possible values are
activeThe item can be used to create new item prices.archivedThe item is no longer active and no new item prices can be created
always returned
Resource object representing item
Returns a list of items satisfying
all the conditions specified in the filter parameters below. The list is sorted by date of creation, in descending order.
Sample Request
curl https://{site}.chargebee.com/api/v2/items \
-G \
-u {site_api_key}:\
--data-urlencode limit=2
copy
curl https://{site}.chargebee.com/api/v2/items \
-G \
-u {site_api_key}:\
--data-urlencode limit=2
Sample Response [ JSON ]
Show more...
{
"list": [
{"item": {
"applicable_items": [
{"id": "day-pass"},
{..}
],
"enabled_for_checkout": true,
"enabled_in_portal": true,
"id": "gold",
"is_giftable": false,
"is_shippable": false,
"item_applicability": "restricted",
"name": "Gold",
"object": "item",
"resource_version": 1599817250235,
"status": "active",
"type": "plan",
"updated_at": 1599817250
}},
{..}
],
"next_offset": "1"
}
URL Format GET
https://{site}.chargebee.com/api/v2/items
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
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.
optional, string filter
Sorts based on the specified attribute.
Supported attributes : name, id, updated_at
Supported sort-orders : asc, desc
Example → sort_by[asc] = "name"
This will sort the result based on the 'name' attribute in ascending(earliest first) order.
optional, string filter
Filter items based on item id.
Supported operators : is, is_not, starts_with, in, not_in
Example → id[is] = "basic"
item_family_id[<operator>]
optional, string filter
Filter items based on item_family_id
.
Supported operators : is, is_not, starts_with, in, not_in
Example → item_family_id[is] = "acme"
optional, enumerated string filter
Filter items based on item type
. Possible values are : plan, addon, charge.
Supported operators : is, is_not, in, not_in
Example → type[is_not] = "plan"
optional, string filter
Filter items based on item name
.
Supported operators : is, is_not, starts_with
Example → name[is_not] = "basic"
item_applicability[<operator>]
optional, enumerated string filter
Filter items based on item_applicability
. Possible values are : all, restricted.
Supported operators : is, is_not, in, not_in
Example → item_applicability[is_not] = "all"
optional, enumerated string filter
Filter items based on item status
. Possible values are : active, archived, deleted.
Supported operators : is, is_not, in, not_in
Example → status[is_not] = "active"
optional, boolean filter
Specifies if gift subscriptions can be created for this item. Possible values are : true, false
Supported operators : is
Example → is_giftable[is] = "true"
optional, timestamp(UTC) in seconds filter
Filter items based on when the items were last updated.
Supported operators : after, before, on, between
Example → updated_at[after] = "1243545465"
enabled_for_checkout[<operator>]
optional, boolean filter
Allow the plan to subscribed to via Checkout. Applies only for plan-items.
Note: Only the in-app version of Checkout is supported for Product Catalog v2. Possible values are : true, false
Supported operators : is
Example → enabled_for_checkout[is] = "null"
enabled_in_portal[<operator>]
optional, boolean filterAllow customers to change their subscription to this plan via the
Self-Serve Portal. Applies only for plan-items. This requires the Portal configuration to
allow changing subscriptions. Possible values are :
true, falseSupported operators : is
Example → enabled_in_portal[is] = "null"
optional, boolean filterSpecifies whether the item undergoes metered billing. When
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, falseSupported operators : is
Example → metered[is] = "true"
usage_calculation[<operator>]
optional, enumerated string filterHow the quantity is calculated from usage data for the item prices belonging to this item. Only applicable when the item is
metered
. This value overrides the one
set at the site level. . Possible values are :
sum_of_usages, last_usage, max_usage.Supported operators : is, is_not, in, not_in
Example → usage_calculation[is] = "SUM_OF_USAGES"
optional, enumerated string filter
The subscription channel this object originated from and is maintained in. Possible values are : web, app_store, play_store.
Supported operators : is, is_not, in, not_in
Example → channel[is_not] = "APP STORE"
always returned
Resource object representing item
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”.
Deletes an item, marking its
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.
Sample Request
curl https://{site}.chargebee.com/api/v2/items/delete-sample/delete \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/items/delete-sample/delete \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{"item": {
"enabled_for_checkout": true,
"enabled_in_portal": true,
"id": "delete-sample",
"is_giftable": false,
"is_shippable": false,
"name": "delete sample",
"object": "item",
"resource_version": 1599817250429,
"status": "deleted",
"type": "addon",
"updated_at": 1599817250
}}
URL Format POST
https://{site}.chargebee.com/api/v2/items/{item_id}/delete
always returned
Resource object representing item