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 ]

API Index URL GET

# 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 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 ]

{"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
}}

{"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
}}

{"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

curl  https://{site}.chargebee.com/api/v2/items/cbdemo_additionaluser \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/items/cbdemo_additionaluser \
     -u {site_api_key}:

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"

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"

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

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

curl  https://{site}.chargebee.com/api/v2/items/delete-sample/delete \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/items/delete-sample/delete \
     -X POST  \
     -u {site_api_key}: