Products

API Version

Product Catalog

Library

Products are offerings that can be sold to customers either as one-time purchases or as recurring subscriptions. These products could include physical items, digital goods, or services that are delivered over a period of time. Chargebee's API allows developers to interact with and manipulate product data, enabling businesses to seamlessly integrate their product offerings into their subscription management workflows.

Sample product [ JSON ]

{
    "created_at": 1678784632,
    "deleted": false,
    "description": "Tshirt for men",
    "external_name": "HRX-TSHIRT",
    "has_variant": false,
    "id": "01GVFNS59M840MZFWPY188H2A1",
    "metadata": {
        "brand": "HRX"
    },
    "name": "HRX TSHIRT",
    "object": "product",
    "resource_version": 1678784632143,
    "shippable": true,
    "status": "active",
    "updated_at": 1678784632
}

API Index URL

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

id

string, max chars=100
The immutable unique identifier of the product.

name

string, max chars=100
A unique display name for the product. This is visible only in Chargebee.

external_name

string, max chars=100
This is a unique name appears for each product to the end user.

description

optional, string, max chars=500
Description of the product.

has_variant

boolean, default=true
Whether the product has variants or not.

status

enumerated string, default=active
Status of the product.

Possible values are

shippable

boolean, default=true
Whether a product is shippable or not.

sku

optional, string, max chars=100
A unique identifier code a seller assigns to each product or item. Retailers and merchants use SKUs to keep track of inventory and sales data and help organize products within a store or warehouse. SKUs can include a combination of letters, numbers, and symbols and can vary in length depending on the seller's needs.

created_at

timestamp(UTC) in seconds
Timestamp when the product was created.

resource_version

optional, long
Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.

updated_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this product was last updated

deleted

boolean, default=false
Determines if the product is deleted or not. If the value is true then the product has been deleted else it exists. Once the product is deleted, you can reuse the product id and name.

metadata

optional, jsonobject
A collection of key-value pairs that provides extra information about the product.

Note: There's a character limit of 65,535.

Learn more.

options
Show attributes [+]

optional, list of option
Array of option list which helps in the product variant creation.

id

string, max chars=100
The immutable unique identifier of the product.

name

string, max chars=100
A unique display name for the product. This is visible only in Chargebee.

external_name

string, max chars=100
This is a unique name appears for each product to the end user.

description

optional, string, max chars=500
Description of the product.

has_variant

boolean, default=true
Whether the product has variants or not.

status

enumerated string, default=active
Status of the product.

Possible values are

shippable

boolean, default=true
Whether a product is shippable or not.

sku

created_at

timestamp(UTC) in seconds
Timestamp when the product was created.

resource_version

updated_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this product was last updated

deleted

metadata

optional, jsonobject
A collection of key-value pairs that provides extra information about the product.

Note: There's a character limit of 65,535.

Learn more.

options

optional, list of option
Array of option list which helps in the product variant creation.

Try in API Explorer

This API creates a new product.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/products \
     -u {site_api_key}:\
     -d name="HRX TSHIRT" \
     -d external_name="HRX-TSHIRT" \
     -d status="ACTIVE" \
     -d description="Tshirt for men" \
     -d metadata='{"brand":"HRX"}'

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "product": {
        "created_at": 1678784632,
        "deleted": false,
        "description": "Tshirt for men",
        "external_name": "HRX-TSHIRT",
        "has_variant": false,
        "id": "01GVFNS59M840MZFWPY188H2A1",
        "metadata": {
            "brand": "HRX"
        },
        "name": "HRX TSHIRT",
        "object": "product",
        "resource_version": 1678784632143,
        "shippable": true,
        "status": "active",
        "updated_at": 1678784632
    }
}

URL Format POST

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

name[]

required, string, max chars=100
A unique internal name for the product. This is only visible in Chargebee.

external_name[]

required, string, max chars=100
The unique name that appears to the end user for each product.

status[]

required, enumerated string, default=active
Status of the product.

Possible values are

id[]

optional, string, max chars=100
The immutable unique identifier of the product. If not passed, it will get autogenerated.

description[]

optional, string, max chars=500
Description of the product.

sku[]

metadata[]

optional, jsonobject
A collection of key-value pairs that provides extra information about the product.

Note: There's a character limit of 65,535.

Learn more.

shippable[]

optional, boolean, default=true
Whether a product is shippable or not. Pass the value as true if it is a shippable physical product, else pass the value as false.

product

always returned
Resource object representing product

Try in API Explorer

Retrieve a product using product_id.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/products/01GVGJYGTDJ72V7NFD3B0TY8N8 \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "product": {
        "created_at": 1678815216,
        "deleted": false,
        "description": "Tshirt for men",
        "external_name": "HRX-TSHIRT",
        "has_variant": false,
        "id": "01GVGJYGTDJ72V7NFD3B0TY8N8",
        "metadata": {
            "brand": "HRX"
        },
        "name": "HRX TSHIRT",
        "object": "product",
        "options": [
            {
                "default_value": "gray",
                "id": "01GVGJYMWBRVMSDND0GREE94X1",
                "name": "color",
                "type": "select",
                "values": [
                    "red",
                    {..}
                ]
            },
            {..}
        ],
        "resource_version": 1678815216000,
        "shippable": true,
        "status": "active",
        "updated_at": 1678815216
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/products/{product-id}

product

always returned
Resource object representing product

Try in API Explorer

This API allows you to update specific product details.

The following table will help you to understand the status of the mapped item and item_price after passing product status value during product updation.

Product Status(Input parameter)	Item and Item Price Status
active	active
inactive	archived

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/products/01GVGK6Y2V82CM94TCX717PRGB \
     -u {site_api_key}:\
     -d name="HRX TSHIRT SPL" \
     -d status="INACTIVE" \
     -d description="Spl Tshirt for mens"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "product": {
        "created_at": 1678815492,
        "deleted": false,
        "description": "Spl Tshirt for mens",
        "external_name": "HRX-TSHIRT",
        "has_variant": false,
        "id": "01GVGK6Y2V82CM94TCX717PRGB",
        "metadata": {
            "brand": "HRX"
        },
        "name": "HRX TSHIRT SPL",
        "object": "product",
        "options": [
            {
                "default_value": "gray",
                "id": "01GVGK6ZWBTX76G6Q0ZTKDZGF7",
                "name": "color",
                "type": "select",
                "values": [
                    "red",
                    {..}
                ]
            },
            {..}
        ],
        "resource_version": 1678815494406,
        "shippable": true,
        "status": "inactive",
        "updated_at": 1678815494
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/products/{product-id}

name[]

optional, string, max chars=100
A unique internal name for the product. This is only visible in Chargebee.

external_name[]

optional, string, max chars=100
The unique name that appears for each product to the end user.

description[]

optional, string, max chars=500
Description of the product.

status[]

optional, enumerated string, default=active
Status of the product. Refer to the table for more information.

Possible values are

sku[]

shippable[]

optional, boolean, default=true
Whether a product is shippable or not. Pass the value as true if it is a shippable physical product, else pass the value as false.

metadata[]

optional, jsonobject
A collection of key-value pairs that provides extra information about the product.

Note: There's a character limit of 65,535.

Learn more.

product

always returned
Resource object representing product

Try in API Explorer

This API deletes a product and changes the delete attribute value to true. Deletion of a product is not allowed if there are active or archived variants under the product or if there are items mapped to the product. Once deleted, the name of the product can be reused.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/products/01GVGKFKQXFVCXC5NA37FFHG4D/delete \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "product": {
        "created_at": 1678815777,
        "deleted": true,
        "description": "Tshirt for men",
        "external_name": "HRX-TSHIRT",
        "has_variant": false,
        "id": "01GVGKFKQXFVCXC5NA37FFHG4D",
        "metadata": {
            "brand": "HRX"
        },
        "name": "HRX TSHIRT",
        "object": "product",
        "options": [
            {
                "default_value": "gray",
                "id": "01GVGKFKZFW0EQV6TPTY41JM7F",
                "name": "color",
                "type": "select",
                "values": []
            },
            {..}
        ],
        "resource_version": 1678815776956,
        "shippable": true,
        "status": "active",
        "updated_at": 1678815776
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/products/{product-id}/delete

product

always returned
Resource object representing product

Try in API Explorer

This API allows you to add, remove, or update product options.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/products/01GVGKAWFV6M8P6FWMXXSTE2K6/update_options \
     -X POST  \
     -u {site_api_key}:\
     -d "options[name][0]"="color" \
     -d "options[default_value][0]"="GRAY" \
     -d "options[values][0]"=["RED","GREEN","GRAY"]

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "product": {
        "created_at": 1678815622,
        "deleted": false,
        "description": "Tshirt for men",
        "external_name": "HRX-TSHIRT",
        "has_variant": false,
        "id": "01GVGKAWFV6M8P6FWMXXSTE2K6",
        "metadata": {
            "brand": "HRX"
        },
        "name": "HRX TSHIRT",
        "object": "product",
        "options": [
            {
                "default_value": "gray",
                "id": "01GVGKAX3SS90R1GW9T6433RMK",
                "name": "color",
                "type": "select",
                "values": [
                    "red",
                    {..}
                ]
            },
            {..}
        ],
        "resource_version": 1678815622000,
        "shippable": true,
        "status": "active",
        "updated_at": 1678815622
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/products/{product-id}/update_options

remove_options[[0..n]][0..n]

optional, list of string
List of options that you want to remove from the product. You can provide option names.

options

Parameters for options. Multiple options can be passed by specifying unique indices.
pass parameters as options[<param name>][<idx:0..n>]

options[name][0..n]

required, string, max chars=100

options[values][0..n]

optional

options[default_value][0..n]

optional, string, max chars=100

product

always returned
Resource object representing product

Try in API Explorer

This API retrieves the list of products that are active or inactive. Use include_deleted parameter to include deleted products with active and inactive products.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/products \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2 \
     --data-urlencode "status[is]"="active"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "product": {
                "created_at": 1678815870,
                "deleted": false,
                "description": "Tshirt for men",
                "external_name": "LP-TSHIRT",
                "has_variant": false,
                "id": "01GVGKJESTP3X5S394G3TW7ZVH",
                "metadata": {
                    "brand": "LP"
                },
                "name": "LP TSHIRT",
                "object": "product",
                "options": [
                    {
                        "default_value": "blue",
                        "id": "01GVGKJEK51XKRD9WTDJK4DE4P",
                        "name": "color",
                        "type": "select",
                        "values": [
                            "pink",
                            {..}
                        ]
                    },
                    {..}
                ],
                "resource_version": 1678815870000,
                "shippable": true,
                "status": "active",
                "updated_at": 1678815870
            }
        },
        {..}
    ]
}

URL Format GET

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

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.

include_deleted[]

optional, boolean, default=false
If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.

sort_by[<sort-order>]

optional, string filter
Sorts based on the specified attribute.
Supported attributes : name, id, created_at, updated_at
Supported sort-orders : asc, desc

Example → sort_by[asc] = "name"
This will sort the result based on the 'name' attribute in ascending(earliest first) order.

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

optional, string filter
Filter product based on their id.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "basic"

name[<operator>]

optional, string filter
Filter product based on their names.
Supported operators : is, is_not, starts_with, in, not_in

Example → name[is] = "basic"

status[<operator>]

optional, enumerated string filter
Filter product based on their status. Possible values are : active, inactive
Supported operators : is, is_not, in, not_in

Example → status[is] = "basic"

shippable[<operator>]

optional, enumerated string filter
Filter product based on whether it is shippable or not. Possible values are : true, false
Supported operators : is

Example → shippable[is] = "true"

has_variant[<operator>]

optional, enumerated string filter
Filter product based on whether it has variants or not. Possible values are : true, false
Supported operators : is

Example → has_variant[is] = "true"

created_at[<operator>]

optional, timestamp(UTC) in seconds filter
Filter product based on their created time.
Supported operators : after, before, on, between

Example → created_at[after] = "1243545465"

updated_at[<operator>]

optional, timestamp(UTC) in seconds filter
Filter product based on their updated time.
Supported operators : after, before, on, between

Example → updated_at[after] = "1243545465"

product

always returned
Resource object representing product

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 product [ JSON ]

API Index URL

Model Class

Product attributes

Consent Fields for Product

Custom Fields for Product

Create a product ¶

Notes

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 a product ¶

Notes

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 a product ¶

Notes

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 a product ¶

Notes

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

Add remove or update options for the product ¶

Notes

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

List products ¶

Notes

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