Settings
API Version
Product Catalog
Library

Item families

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

Model Class

<cb_client>.ItemFamily

Item family attributes

id
string, max chars=50
The identifier for the item family. It is unique and immutable.
name
string, max chars=50
A unique display name for the item family. This is visible only in Chargebee and not to customers.
description
optional, string, max chars=500
Description of the item family. This is visible only in Chargebee and not to customers.
status
optional, enumerated string
Status of the item family.
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.
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.
Show all values[+]
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
When the item family was last updated.
channel
optional, enumerated string
The 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.
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.
Show all values[+]
business_entity_id
optional, string, max chars=50
The unique ID of the business entity of this item_family. 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.
deleted
boolean
Indicates whether the item family has been deleted or not.
id id
string, max chars=50
The identifier for the item family. It is unique and immutable.
name name
string, max chars=50
A unique display name for the item family. This is visible only in Chargebee and not to customers.
description description
optional, string, max chars=500
Description of the item family. This is visible only in Chargebee and not to customers.
status status
optional, enumerated string
Status of the item family.
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.
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.
Show all values[+]
resource_version 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 updated_at
optional, timestamp(UTC) in seconds
When the item family was last updated.
channel channel
optional, enumerated string
The 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.
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.
Show all values[+]
business_entity_id business_entity_id
optional, string, max chars=50
The unique ID of the business entity of this item_family. 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.
deleted deleted
boolean
Indicates whether the item family has been deleted or not.

Consent Fields for Item family

Custom Fields for Item family

Create an item family

Idempotency Supported

This endpoint creates an item family for your product line or service.

Notes

Sample Codes 
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.ItemFamily.create(
    cb_client.ItemFamily.CreateParams(
        id="acme-inc",
        description="Acme Inc Family",
        name="Acme Inc Family"
    )
)
item_family = response.item_family
copy
Click to Copy
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.ItemFamily.create(
    cb_client.ItemFamily.CreateParams(
        id="acme-inc",
        description="Acme Inc Family",
        name="Acme Inc Family"
    )
)
item_family = response.item_family

Sample Result [ 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

Method

<cb_client>.ItemFamily.create({<param name> : <value>,<param name> : <value> ...})

Input Parameters

id[]
required, string, max chars=50
The identifier for the item family. Must be unique and is immutable.
name[]
required, string, max chars=50
The display name for the item family. Must be unique. This is visible only in Chargebee and not to customers.
description[]
optional, string, max chars=500
Description of the item family. This is visible only in Chargebee and not to customers.
business_entity_id[]
optional, string, max chars=50
The unique ID of the business entity for this item_family. 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.

.

Returns

item_family item_family
always returned
Resource object representing item_family

Sample admin console URL

https://{site}.chargebee.com/admin-console/item_families/123x

Retrieve an item family

This endpoint retrieves an item family based on the item family id.

Notes

Sample Codes 
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.ItemFamily.retrieve("acme-inc")
item_family = response.item_family
copy
Click to Copy
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.ItemFamily.retrieve("acme-inc")
item_family = response.item_family

Sample Result [ JSON ]

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

URL Format GET

https://{site}.chargebee.com/api/v2/item_families/{item-family-id}

Method

<cb_client>.ItemFamily.retrieve(<item_family_id>,{<param name> : <value>,<param name> : <value> ...})

Returns

item_family item_family
always returned
Resource object representing item_family

Sample admin console URL

https://{site}.chargebee.com/admin-console/item_families/123x

List item families

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.

Notes

Sample Codes 
from chargebee import Chargebee, Filters

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
entries = cb_client.ItemFamily.list(
    cb_client.ItemFamily.ListParams(
        limit=5
    )
)
for entry in entries.list:
    item_family = entry.item_family
copy
Click to Copy
from chargebee import Chargebee, Filters

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
entries = cb_client.ItemFamily.list(
    cb_client.ItemFamily.ListParams(
        limit=5
    )
)
for entry in entries.list:
    item_family = entry.item_family

Sample Result [ 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

Method

<cb_client>.ItemFamily.list({<param name> : <value>,<param name> : <value> ...})

Input Parameters

limit[]
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset[]
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.
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
optional, string filter
The identifier for the item family. It is unique and immutable. Possible values are :
Supported operators : is, is_not, starts_with, in, not_in

Example → "id[is]" : "family-id"
is
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
is_not
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
starts_with
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
in
optional, string filter
Possible values are :
Supported operators :

Example →
not_in
optional, string filter
Possible values are :
Supported operators :

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

Example → "name[is]" : "family-name"
is
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
is_not
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
starts_with
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
updated_at[<operator>]
optional, timestamp(UTC) in seconds filter
When the item family was last updated. Possible values are :
Supported operators : after, before, on, between

Example → "updated_at[after]" : "1243545465"
after
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example →
before
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example →
on
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example →
between
optional, string filter
Possible values are :
Supported operators :

Example →
business_entity_id[<operator>]
optional, enumerated string filter
The unique ID of the business entity of this item_family. Learn more about all the scenarios before using this filter. Possible values are : true, false
Supported operators : is_present, is

Example → "business_entity_id[is_present]" : "business_entity_id"
is_present
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example →
is
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
include_site_level_resources[<operator>]
optional, enumerated string filter

Default value is true . To exclude site-level resources in specific cases, set this parameter to false.

 Possible values are : true, false
Supported operators : is

Example → "include_site_level_resources[is]" : "null"
is
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example →

Returns

item_family item_family
always returned
Resource object representing item_family
next_offset 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`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/item_families/123x

Update an item family

Idempotency Supported
This endpoint updates the name and/or description of the item family.

Notes

Sample Codes 
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.ItemFamily.update("acme-inc",
    cb_client.ItemFamily.UpdateParams(
        description="Acme Inc Family"
    )
)
item_family = response.item_family
copy
Click to Copy
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.ItemFamily.update("acme-inc",
    cb_client.ItemFamily.UpdateParams(
        description="Acme Inc Family"
    )
)
item_family = response.item_family

Sample Result [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/item_families/{item-family-id}

Method

<cb_client>.ItemFamily.update(<item_family_id>,{<param name> : <value>,<param name> : <value> ...})

Input Parameters

name[]
optional, string, max chars=50
The display name for the item family. Must be unique. This is visible only in Chargebee and not to customers.
description[]
optional, string, max chars=500
Description of the item family. This is visible only in Chargebee and not to customers.

Returns

item_family item_family
always returned
Resource object representing item_family

Sample admin console URL

https://{site}.chargebee.com/admin-console/item_families/123x

Delete an item family

Idempotency Supported
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.

Notes

Sample Codes 
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.ItemFamily.delete("acme-inc")
item_family = response.item_family
copy
Click to Copy
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.ItemFamily.delete("acme-inc")
item_family = response.item_family

Sample Result [ JSON ]

Show more...
{
    "item_family": {
        "description": "Acme Inc Family",
        "id": "acme-inc",
        "name": "Acme Inc Family",
        "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

Method

<cb_client>.ItemFamily.delete(<item_family_id>,{<param name> : <value>,<param name> : <value> ...})

Returns

item_family item_family
always returned
Resource object representing item_family

Sample admin console URL

https://{site}.chargebee.com/admin-console/item_families/123x