Item families

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

https://{site}.chargebee.com/api/v2/item_families

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

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

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

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

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

business_entity_id

deleted

boolean
Indicates whether the item family has been deleted or not.

Try in API Explorer

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

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

200:

STATUS

Sample Response [ JSON ]

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

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.

item_family

always returned
Resource object representing item_family

Try in API Explorer

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

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/item_families/acme-inc \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

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

item_family

always returned
Resource object representing item_family

Try in API Explorer

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

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

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

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.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "family-id"

name[<operator>]

optional, string filter
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"

updated_at[<operator>]

optional, timestamp(UTC) in seconds filter
When the item family was last updated.
Supported operators : after, before, on, between

Example → updated_at[after] = "1243545465"

business_entity_id[<operator>]

optional, string filter
The unique ID of the business entity of this item_family. Learn more about all the scenarios before using this filter.
Supported operators : is, is_present

Example → business_entity_id[is] = "business_entity_id"

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"

item_family

always returned
Resource object representing item_family

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

Try in API Explorer

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

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

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

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

always returned
Resource object representing item_family

Try in API Explorer

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

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/item_families/acme-inc/delete \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

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

item_family

always returned
Resource object representing item_family

Sample item family [ JSON ]

API Index URL

Model Class

Item family attributes

Consent Fields for Item family

Custom Fields for Item family

Create an item family ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve an item family ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List item families ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Update an item family ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Delete an item family ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL