API Version
Product Catalog
Library

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

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.
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.
Show all values[+]
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.
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.

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

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/item_families \
     -u {site_api_key}:\
     -d id="acme-inc" \
     -d description="Acme Inc Family" \
     -d name="Acme Inc Family"
copy
Click to Copy

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

Method

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

Sample admin console URL

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

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

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/item_families/acme-inc \
     -u {site_api_key}:
copy
Click to Copy

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

item_family item_family
always returned
Resource object representing item_family

Sample admin console URL

https://{site}.chargebee.com/admin-console/item_families/123x
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 Request
curl  https://{site}.chargebee.com/api/v2/item_families \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5
copy
Click to Copy

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

Method

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"
id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
id[not_in][operator]
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"
name[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
name[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
name[starts_with][operator]
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"
updated_at[after][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
updated_at[before][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
updated_at[on][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
updated_at[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
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
This endpoint updates the name and/or description of the item family.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/item_families/acme-inc \
     -u {site_api_key}:\
     -d description="Acme Inc Family"
copy
Click to Copy

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

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

Sample admin console URL

https://{site}.chargebee.com/admin-console/item_families/123x
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 Request
curl  https://{site}.chargebee.com/api/v2/item_families/acme-inc/delete \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

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

item_family item_family
always returned
Resource object representing item_family

Sample admin console URL

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