Settings
Configure SDK
Items
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
Description of the item. This is visible only in Chargebee and not to customers.
Note:
- The description field supports up to 2000 characters, including HTML tags. The inner text (excluding HTML tags) must not exceed 500 characters.
For example:
- testing - desc.
Total with tags: 38 characters,
inner text: 'testing desc' (12 characters). - If your input includes characters requiring sanitization, such as incomplete HTML tags, the sanitization process may alter the input and increase its length. If the sanitized content exceeds the allowed limit, the request will be rejected.
The id
of the Item family
that the item belongs to. Is mandatory when Product Families
have been enabled.
Allow 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 .
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
.
Indicates 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.
The 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.
Specifies 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.
How 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
.
A collection of key-value pairs that provides extra information about the item. Learn more .
The unique ID of the business entity of this item. This is applicable only when multiple business entities have been created for the site. The value of this attribute indicates that the resource is specific to the given business entity.
The 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.
The list of items(plans, addons, and charges) added to the bundle plan. This attribute is only available when the item_type
is plan
.
This attribute holds additional information about the bundle item. This attribute is only available when the item_type
is plan
.
Create an item ¶
Creates a new item.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Description of the item. This is visible only in Chargebee and not to customers.
Note:
- The description field supports up to 2000 characters, including HTML tags. The inner text (excluding HTML tags) must not exceed 500 characters.
For example:
- testing - desc.
Total with tags: 38 characters,
inner text: 'testing desc' (12 characters). - If your input includes characters requiring sanitization, such as incomplete HTML tags, the sanitization process may alter the input and increase its length. If the sanitized content exceeds the allowed limit, the request will be rejected.
The id
of the Item family
that the item belongs to. Is mandatory when Product Families
have been enabled.
Allow 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.
Indicates 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.
The 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.
The 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.
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
.
Specifies 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.
How 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.
.
A collection of key-value pairs that provides extra information about the item.
Note: There's a character limit of 65,535.
The unique ID of the business entity
for this item.
This is applicable only when multiple business entities have been created for the site. When provided, the operation will read or write data associated with the specified business entity. If not provided, the resource will be created at the site level, and the business_entity_id
will not be included in the API response.
Note An alternative way of passing this parameter is by means of a custom HTTP header.
.
pass parameters as bundle_items_to_add[<param name>][<idx:0..n>]
Returns
Resource object representing item
Retrieve an item ¶
Retrieve an item resource.
Sample Response [ JSON ]
URL Format GET
Returns
Resource object representing item
Update an item ¶
Updates an item with the changes specified. Unspecified item parameters are not modified.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Description of the item. This is visible only in Chargebee and not to customers.
Note:
- The description field supports up to 2000 characters, including HTML tags. The inner text (excluding HTML tags) must not exceed 500 characters.
For example:
- testing - desc.
Total with tags: 38 characters,
inner text: 'testing desc' (12 characters). - If your input includes characters requiring sanitization, such as incomplete HTML tags, the sanitization process may alter the input and increase its length. If the sanitized content exceeds the allowed limit, the request will be rejected.
The id
of the Item family
that the item belongs to. Is mandatory when Product Families
have been enabled.
Allow 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 .
Indicates 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.
The 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.
The 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.
A collection of key-value pairs that provides extra information about the item. Learn more .
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
.
pass parameters as bundle_items_to_add[<param name>][<idx:0..n>]
pass parameters as bundle_items_to_update[<param name>][<idx:0..n>]
pass parameters as bundle_items_to_remove[<param name>][<idx:0..n>]
Returns
Resource object representing item
List items ¶
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 Response [ JSON ]
URL Format GET
Input Parameters
Filter Params
For operator usages, see the Pagination and Filtering section.
Filter items based on when the items were last updated. Supported operators : after, before, on, between
Example → updated_at[after] = "1243545465"
Supported operators : after, before, on, between
Example → updated_at[after] = "1243545465"
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, falseSupported operators : is
Example → enabled_for_checkout[is] = "null"
Allow 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"
Specifies 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.
Supported operators : is
Example → metered[is] = "true"
How 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.
Supported operators : is, is_not, in, not_in
Example → usage_calculation[is] = "SUM_OF_USAGES"
The unique ID of the
business entity
of this item.
Learn more
about all the scenarios before using this filter.
Supported operators : is, is_present
Example → business_entity_id[is_present] = "true"
Possible values are : true, falseSupported operators : is_present, is
Example → business_entity_id[is_present] = "business_entity_id"
Default value is true . To exclude site-level resources in specific cases, set this parameter to false.
Supported operators : is
Example → include_site_level_resources[is] = "null"
Parameters of bundle_configuration
pass parameters as bundle_configuration[<param name>][<operator>]
Returns
Resource object representing item
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`.
Delete an item ¶
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 Response [ JSON ]
URL Format POST
Returns
Resource object representing item