If you’re a company that sells multiple product lines then each product line or service is an item family in the Chargebee API. For example, if you are a SaaS company that offers separate products for project management, content collaboration, and customer support. Each of those can be an item family under which the various plans, addons and charges can be the items.

Item families compartmentalize items such that only items belonging to the same family can be part of any given subscription.

Note:
You must have the Product Families enabled for your site to be able to set up item families.

Sample item family [ JSON ]

{ "description": "Acme Inc Family", "id": "acme-inc", "name": "Acme Inc Family", "resource_version": 1576400459324, "updated_at": 1576400459 }

API Index URL GET

https://{site}.chargebee.com/api/v2/item_families
id
The identifier for the item family. It is unique and immutable.
string, max chars=50
name
A unique display name for the item family. This is visible only in Chargebee and not to customers.
string, max chars=50
description
Description of the item family. This is visible only in Chargebee and not to customers.
optional, string, max chars=500
status

optional, enumerated string
Possible values are
activeThe item family is active and can be used to create new items.deletedThe item family has been deleted and cannot be used to create new items. The id and name can be reused to create a new item family.
resource_version
Version number of this resource. Each update of this resource results in an incremental change of this number.
optional, long
updated_at
When the item family was last updated.
optional, timestamp(UTC) in seconds
Sample Request
curl  https://{site}.chargebee.com/api/v2/item_families \
     -X POST  \
     -u {site_api_key}:\
     -d id="acme-inc" \
     -d description="Acme Inc Family" \
     -d name="Acme Inc Family"
copy
curl  https://{site}.chargebee.com/api/v2/item_families \
     -X POST  \
     -u {site_api_key}:\
     -d id="acme-inc" \
     -d description="Acme Inc Family" \
     -d name="Acme Inc Family"

Sample Response [ JSON ]

Show more...
{"item_family": { "description": "Acme Inc Family", "id": "acme-inc", "name": "Acme Inc Family", "resource_version": 1576400459324, "updated_at": 1576400459 }}

URL Format POST

https://{site}.chargebee.com/api/v2/item_families
id
The identifier for the item family. Must be unique and is immutable.
required, string, max chars=50
name
The display name for the item family. Must be unique. This is visible only in Chargebee and not to customers.
required, string, max chars=50
description
Description of the item family. This is visible only in Chargebee and not to customers.
optional, string, max chars=500
Resource object representing item_family.
always returned
Sample Request
curl  https://{site}.chargebee.com/api/v2/item_families/acme-inc-2019 \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/item_families/acme-inc-2019 \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"item_family": { "description": "Acme Inc 2019 products", "id": "acme-inc-2019", "name": "Acme Inc 2019", "resource_version": 1576400460009, "updated_at": 1576400460 }}

URL Format GET

https://{site}.chargebee.com/api/v2/item_families/{item_family_id}
Resource object representing item_family.
always returned
Returns a list of item families 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/item_families \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5
copy
curl  https://{site}.chargebee.com/api/v2/item_families \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5

Sample Response [ JSON ]

Show more...
{"list": [ {"item_family": { "description": "Acme Inc Family", "id": "acme-inc", "name": "Acme Inc Family", "resource_version": 1576400459324, "updated_at": 1576400459 }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v2/item_families
limit
The number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
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, max chars=1000
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
The identifier for the item family. It is unique and immutable.
Supported operators : is, is_not, starts_with, in, not_in

Example id[is] = "family-id"
optional, string filter
name[<operator>]
A unique display name for the item family. This is visible only in Chargebee and not to customers.
Supported operators : is, is_not, starts_with

Example name[is] = "family-name"
optional, string filter
updated_at[<operator>]
When the item family was last updated.
Supported operators : after, before, on, between

Example updated_at[after] = "1243545465"
optional, timestamp(UTC) in seconds filter
Resource object representing item_family.
always returned
next_offset
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”.
optional, string, max chars=1000
Updates the name and/or description of the item family.
Sample Request
curl  https://{site}.chargebee.com/api/v2/item_families/acme-inc-2018 \
     -X POST  \
     -u {site_api_key}:\
     -d description="Acme Inc 2018 products"
copy
curl  https://{site}.chargebee.com/api/v2/item_families/acme-inc-2018 \
     -X POST  \
     -u {site_api_key}:\
     -d description="Acme Inc 2018 products"

Sample Response [ JSON ]

Show more...
{"item_family": { "description": "Acme Inc 2018 products", "id": "acme-inc-2018", "name": "Acme Inc 2018", "resource_version": 1576400460281, "updated_at": 1576400460 }}

URL Format POST

https://{site}.chargebee.com/api/v2/item_families/{item_family_id}
name
The display name for the item family. Must be unique. This is visible only in Chargebee and not to customers.
optional, string, max chars=50
description
Description of the item family. This is visible only in Chargebee and not to customers.
optional, string, max chars=500
Resource object representing item_family.
always returned
Deletes an item family, marking its status as deleted. This is not allowed if there are active items under the item family. Once deleted, the id and name of the item family can be reused to create a new item family.
Sample Request
curl  https://{site}.chargebee.com/api/v2/item_families/acme-inc-2020/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/item_families/acme-inc-2020/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"item_family": { "description": "Acme Inc 2020 products", "id": "acme-inc-2020", "name": "Acme Inc 2020", "object": "item_family", "resource_version": 1591686231210, "status": "deleted", "updated_at": 1591686231 }}

URL Format POST

https://{site}.chargebee.com/api/v2/item_families/{item_family_id}/delete
Resource object representing item_family.
always returned