Variants

API Version

Product Catalog

Library

A product variant is a specific product version with a unique combination of product option values.

Sample variant [ JSON ]

{
    "created_at": 1678887627,
    "deleted": false,
    "description": "T-shirt for men",
    "external_name": "Red Small T-shirt1678887627471",
    "id": "01GVJR0ASC2AB80F7KATTCMWFB",
    "metadata": {
        "brand": "HRX"
    },
    "name": "Red S T-shirt1678887627471",
    "object": "variant",
    "option_values": [
        {
            "name": "color",
            "value": "red"
        },
        {
            "name": "size",
            "value": "s"
        }
    ],
    "product_id": "01GVJR0A1TZ5AMR6PPBEG85Q09",
    "resource_version": 1678887627621,
    "sku": "sku-12346780",
    "status": "active",
    "updated_at": 1678887627
}

API Index URL

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

id

optional, string, max chars=100
The immutable unique identifier of a product variant.

name

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

external_name

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

description

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

sku

optional, string, max chars=100
A unique identifier code a seller assigns to each product variant. 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.

deleted

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

product_id

string, max chars=100
The unique identifier of the product that is associated with this variant.

status

optional, enumerated string
Status of the product variant.

Possible values are

created_at

timestamp(UTC) in seconds
Timestamp when the product variant 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 variant was last updated.

metadata

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

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

Learn more.

option_values
Show attributes [+]

optional, list of option_value
List of product variants option values.

id

optional, string, max chars=100
The immutable unique identifier of a product variant.

name

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

external_name

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

description

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

sku

deleted

product_id

string, max chars=100
The unique identifier of the product that is associated with this variant.

status

optional, enumerated string
Status of the product variant.

Possible values are

created_at

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

resource_version

updated_at

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

metadata

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

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

Learn more.

option_values

optional, list of option_value
List of product variants option values.

Try in API Explorer

This API is used for creating a new product variant.

The following table will help you to understand the state of the variant status after passing status value during variant creation.

Parameter Value column holds possible inputs to the variant.status.
Product Status column states the status of the associated product.
Variant Status column states the value of the variant status once the variant is created.

Parameter Value	Product Status	Variant Status
No value passed	active	active
No value passed	inactive	inactive
Value passed as active	active	active
Value passed as inactive	active	inactive
Value passed as active	inactive	not allowed
Value passed as inactive	inactive	inactive

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/products/01GVJR0A1TZ5AMR6PPBEG85Q09/variants \
     -X POST  \
     -u {site_api_key}:\
     -d name="Red S T-shirt1678887627471" \
     -d external_name="Red Small T-shirt1678887627471" \
     -d sku="sku-12346780" \
     -d description="T-shirt for men" \
     -d status="ACTIVE" \
     -d metadata='{"brand":"HRX"}' \
     -d "option_values[name][0]"="color" \
     -d "option_values[value][0]"="red" \
     -d "option_values[name][1]"="size" \
     -d "option_values[value][1]"="s"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "variant": {
        "created_at": 1678887627,
        "deleted": false,
        "description": "T-shirt for men",
        "external_name": "Red Small T-shirt1678887627471",
        "id": "01GVJR0ASC2AB80F7KATTCMWFB",
        "metadata": {
            "brand": "HRX"
        },
        "name": "Red S T-shirt1678887627471",
        "object": "variant",
        "option_values": [
            {
                "name": "color",
                "value": "red"
            },
            {..}
        ],
        "product_id": "01GVJR0A1TZ5AMR6PPBEG85Q09",
        "resource_version": 1678887627621,
        "sku": "sku-12346780",
        "status": "active",
        "updated_at": 1678887627
    }
}

URL Format POST

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

id[]

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

name[]

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

external_name[]

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

description[]

optional, string, max chars=500
A detailed description of this product variant.

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.

status[]

optional, enumerated string
Status of the product variant. Refer to the table for more information.

Possible values are

option_values

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

option_values[name][0..n]

required, string, max chars=100

option_values[value][0..n]

required, string, max chars=100

variant

always returned
Resource object representing variant

Try in API Explorer

This API is used to retrieve a product variant using variant_id.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "variant": {
        "created_at": 1678887632,
        "deleted": false,
        "description": "Red Medium T-shirt for men",
        "external_name": "Red Medium T-shirt1678887631188",
        "id": "01GVJR0EHF9X3RM1JHQYQBKYG7",
        "name": "Red M T-shirt1678887631188",
        "object": "variant",
        "option_values": [
            {
                "name": "size",
                "value": "m"
            },
            {..}
        ],
        "product_id": "01GVJR0DS3VCGE3FMEH8WD5A42",
        "resource_version": 1678887632000,
        "sku": "sku-12346781",
        "status": "active",
        "updated_at": 1678887632
    }
}

URL Format GET

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

variant

always returned
Resource object representing variant

Try in API Explorer

This API is used to modify a product variant.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/variants/01GVJR0FWF7HNWH93VD2QKC8P9 \
     -u {site_api_key}:\
     -d name="Blue L T-shirt1678887632951" \
     -d external_name="Blue XLarge T-shirt1678887632951" \
     -d sku="sku-1234679" \
     -d description="Blue XLarge T-shirt for men" \
     -d status="ACTIVE"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "variant": {
        "created_at": 1678887633,
        "deleted": false,
        "description": "Blue XLarge T-shirt for men",
        "external_name": "Blue XLarge T-shirt1678887632951",
        "id": "01GVJR0FWF7HNWH93VD2QKC8P9",
        "name": "Blue L T-shirt1678887632951",
        "object": "variant",
        "option_values": [
            {
                "name": "color",
                "value": "red"
            },
            {..}
        ],
        "product_id": "01GVJR0FC03W10PTT5Y5TYPTD8",
        "resource_version": 1678887633036,
        "sku": "sku-1234679",
        "status": "active",
        "updated_at": 1678887633
    }
}

URL Format POST

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

name[]

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

description[]

optional, string, max chars=500
A detailed description of this product variant.

status[]

optional, enumerated string
Status of the product variant.

Possible values are

external_name[]

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

sku[]

metadata[]

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

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

Learn more.

variant

always returned
Resource object representing variant

Try in API Explorer

This API deletes a product variant and returns the delete attribute value as true. Deletion of a product variant is not allowed if there are active or archived item_price_id under the variant. Once the variant is deleted, the id and name of the product variant 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/variants/01GVJR0BZWQNK469QKE05AEMC2/delete \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "variant": {
        "created_at": 1678887629,
        "deleted": true,
        "description": "Red XLarge T-shirt for men",
        "external_name": "Red XLarge T-shirt1678887628727",
        "id": "01GVJR0BZWQNK469QKE05AEMC2",
        "name": "Red XL T-shirt1678887628727",
        "object": "variant",
        "option_values": [
            {
                "name": "color",
                "value": "red"
            },
            {..}
        ],
        "product_id": "01GVJR0B9KF1BQE9GB19CNQFDR",
        "resource_version": 1678887629125,
        "sku": "sku-12346783",
        "status": "active",
        "updated_at": 1678887629
    }
}

URL Format POST

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

variant

always returned
Resource object representing variant

Try in API Explorer

This API retrieves the list of product variants.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/products/01GTBG0C1BR59BY8ARK1640ZGT/variants \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "variant": {
                "option_values": [
                    {
                        "name": "color",
                        "value": "red"
                    },
                    {..}
                ],
                "created_at": 1677570619,
                "deleted": false,
                "description": "T-shirt for men",
                "external_name": "Red XXLarge T-shirt1677570618284",
                "id": "01GTBG0D29TMDZRGMFVRFY5X35",
                "metadata": {
                    "brand": "HRX"
                },
                "name": "Red XXL T-shirt1677570618284",
                "object": "variant",
                "product_id": "01GTBG0C1BR59BY8ARK1640ZGT",
                "resource_version": 1677570619000,
                "sku": "sku-12346780",
                "status": "active",
                "updated_at": 1677570619
            }
        },
        {..}
    ]
}

URL Format GET

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

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, status, 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 variant based on their id.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "basic"

name[<operator>]

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

Example → name[is] = "basic"

sku[<operator>]

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

Example → sku[is] = "basic"

status[<operator>]

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

Example → status[is] = "active"

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] = "basic"

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] = "basic"

variant

always returned
Resource object representing variant

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

API Index URL

Model Class

Variant attributes

Event types

Consent Fields for Variant

Custom Fields for Variant

Create a product variant ¶

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 variant ¶

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 variant ¶

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 variant ¶

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

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