ChargebeeAPI

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 ItemJSON

Items attributes

id
required, string, max chars=100

The identifier for the item. It is unique and immutable.

name
required, string, max chars=100

A unique display name for the item. This is visible only in Chargebee and not to customers.

external_name
optional, string, max chars=100

A unique display name for the item.

status
optional, enumerated string

The status of the item.

Possible Enum Values
active

The item can be used to create new item prices.

archived

The item is no longer active and no new item prices can be created

deleted

Indicates that the item has been deleted. The id and name can be reused. Deleted items can be retrieved using List items .

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

Timestamp indicating when the item was last updated.

item_family_id
optional, string, max chars=100

The id of the Item family that the item belongs to. Is mandatory when Product Families have been enabled.

type
required, enumerated string

The type of the item.

Possible Enum Values
plan

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

addon

A recurring component that can be added to a subscription in addition to its plan.

charge

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

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

is_giftable
required, boolean, default=false

Specifies if gift subscriptions can be created for this item.

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

enabled_for_checkout
required, boolean, default=true

Allow the plan to subscribed to via Checkout. Applies only for plan-items. Note: Only the in-app layout of Checkout is supported.

enabled_in_portal
required, boolean, default=true

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 .

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

item_applicability
optional, enumerated string, default=all

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.

Possible Enum Values
all

all addon-items and charge-items are applicable to this plan-item.

restricted

only the addon-items or charge-items provided in applicable_items can be applied to this plan-item.

gift_claim_redirect_url
optional, string, max chars=500

The URL to redirect to once the gift has been claimed by the receiver.

unit
optional, string, max chars=30

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.
metered
required, boolean, default=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.

usage_calculation
optional, enumerated string

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 .

Possible Enum Values
sum_of_usages

the net quantity is the sum of the quantity of all usages for the current term.

last_usage

from 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_usage

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

is_percentage_pricing
optional, boolean, default=false
archived_at
optional, timestamp(UTC) in seconds

Timestamp indicating when this item was archived.

channel
optional, enumerated string

The subscription channel this object originated from and is maintained in.

Possible Enum Values
web

The object was created (and is maintained) for the web channel directly in Chargebee via API or UI.

app_store

The 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_store

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

metadata
optional, jsonobject

A collection of key-value pairs that provides extra information about the item. Learn more .

deleted
required, boolean

Indicates whether the item has been deleted or not.

business_entity_id
optional, string, max chars=50

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.

applicable_items
optional, list of applicable_item

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.

bundle_items
optional, list of bundle_item

The list of items(plans, addons, and charges) added to the bundle plan. This attribute is only available when the item_type is plan .

bundle_configuration
optional, bundle_configuration

This attribute holds additional information about the bundle item. This attribute is only available when the item_type is plan .