Price variants

API Version

Product Catalog

Library

Price variant resource offers businesses the flexibility to manage pricing for multiple variations of an item (plan, addon, or charge) in the Product Catalog. It enables the creation of diverse pricing structures based on variables such as geography, partners, versions, and more.

See also: For a more detailed understanding of Price Variants, including how to enable, configure, and manage them, as well as their impact on other features, follow these resources:

Sample price variant [ JSON ]

{
    "updated_at": 1709200385,
    "name": "Germany Berlin",
    "created_at": 1709200385,
    "attributes": [
        {
            "name": "country",
            "value": "germany"
        },
        {
            "name": "city",
            "value": "berlin"
        }
    ],
    "id": "germany-berlin",
    "external_name": "Germany",
    "resource_version": 1709200385728,
    "status": "active",
    "object": "price_variant"
}

API Index URL

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

id

string, max chars=100
The unique and immutable identifier of the price variant.

name

string, max chars=100
A unique name of the price variant.

external_name

optional, string, max chars=100
A unique display name for the price variant.

variant_group

optional, string, max chars=100
The variant_group organizes similar price_variants to optimize strategies such as bundling, geo-based pricing experiments, and campaign-specific pricing like cb-atomic-pricing- for effective grouping. The variant_group provides greater flexibility and precision in your pricing models.

description

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

status

optional, enumerated string
Status of a price variant.

Possible values are

created_at

timestamp(UTC) in seconds
Timestamp indicating when this price variant is created.

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
Timestamp indicating when this price variant was last updated.

archived_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this price variant was archived.

business_entity_id

optional, string, max chars=50
The unique ID of the business entity of this price_variant. 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 price variant has been deleted or not.

attributes
Show attributes [+]

optional, list of attribute

The list of price variant attribute values.

Attributes can be used to store additional information about the price variant. For example, for a price variant called 'Germany', the attributes can be 'Country':'Germany', 'City':'Berlin' and so on.

id

string, max chars=100
The unique and immutable identifier of the price variant.

name

string, max chars=100
A unique name of the price variant.

external_name

optional, string, max chars=100
A unique display name for the price variant.

variant_group

description

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

status

optional, enumerated string
Status of a price variant.

Possible values are

created_at

timestamp(UTC) in seconds
Timestamp indicating when this price variant is created.

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
Timestamp indicating when this price variant was last updated.

archived_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this price variant was archived.

business_entity_id

deleted

boolean
Indicates whether the price variant has been deleted or not.

attributes

optional, list of attribute

The list of price variant attribute values.

Try in API Explorer

This endpoint allows the creation of a new price variant that can be attached to item prices.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/price_variants \
     -u {site_api_key}:\
     -d id="germany-berlin" \
     -d name="Germany Berlin" \
     -d external_name="Germany" \
     -d "attributes[name][0]"="country" \
     -d "attributes[value][0]"="germany" \
     -d "attributes[name][1]"="city" \
     -d "attributes[value][1]"="berlin"

copy

Click to Copy

Create a price variant

200:

STATUS

Sample Response [ JSON ]

{
    "price_variant": {
        "updated_at": 1709200385,
        "name": "Germany Berlin",
        "created_at": 1709200385,
        "attributes": [
            {
                "name": "country",
                "value": "germany"
            },
            {..}
        ],
        "id": "germany-berlin",
        "external_name": "Germany",
        "resource_version": 1709200385728,
        "status": "active",
        "object": "price_variant"
    }
}

URL Format POST

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

id[]

required, string, max chars=100
The unique and immutable identifier of the price variant.

name[]

required, string, max chars=100
A unique name of the price variant.

external_name[]

optional, string, max chars=100
A unique display name for the price variant.

description[]

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

variant_group[]

business_entity_id[]

optional, string, max chars=50
The unique ID of the business entity for this price_variant. 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.

attributes

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

attributes[name][0..n]

required, string, max chars=100

attributes[value][0..n]

required, string, max chars=100

price_variant

always returned
Resource object representing price_variant

Try in API Explorer

This endpoint retrieves the details of a specific price variant using its unique identifier.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/price_variants/germany-berlin \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "price_variant": {
        "updated_at": 1709200385,
        "name": "Germany Berlin",
        "created_at": 1709200385,
        "attributes": [
            {
                "name": "country",
                "value": "germany"
            },
            {..}
        ],
        "id": "germany-berlin",
        "external_name": "Germany",
        "resource_version": 1709200385728,
        "status": "active",
        "object": "price_variant"
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/price_variants/{price-variant-id}

price_variant

always returned
Resource object representing price_variant

Try in API Explorer

This endpoint modifies the details of an existing price variant.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/price_variants/germany-munich \
     -u {site_api_key}:\
     -d name="Germany Munich - Web Sales" \
     -d "attributes[name][0]"="country" \
     -d "attributes[value][0]"="germany" \
     -d "attributes[name][1]"="city" \
     -d "attributes[value][1]"="munich" \
     -d "attributes[name][2]"="channel" \
     -d "attributes[value][2]"="web"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "price_variant": {
        "updated_at": 1709200387,
        "name": "Germany Munich - Web Sales",
        "created_at": 1709200386,
        "attributes": [
            {
                "name": "country",
                "value": "germany"
            },
            {..}
        ],
        "id": "germany-munich",
        "external_name": "Germany",
        "resource_version": 1709200387080,
        "status": "active",
        "object": "price_variant"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/price_variants/{price-variant-id}

name[]

optional, string, max chars=100
A unique name of the price variant.

external_name[]

optional, string, max chars=100
A unique display name for the price variant.

description[]

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

variant_group[]

status[]

optional, enumerated string
Status of a price variant.

Possible values are

attributes

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

attributes[name][0..n]

required, string, max chars=100

attributes[value][0..n]

required, string, max chars=100

price_variant

always returned
Resource object representing price_variant

Try in API Explorer

Deletes the price variant. This is not allowed if price variant is attached to any item price. Once deleted, the id and name of the price 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/price_variants/delete-sample/delete \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "price_variant": {
        "updated_at": 1709200386,
        "name": "delete sample",
        "created_at": 1709200386,
        "attributes": [
            {
                "name": "country",
                "value": "germany"
            },
            {..}
        ],
        "id": "delete-sample",
        "external_name": "delete sample",
        "resource_version": 1709200386268,
        "status": "deleted",
        "object": "price_variant"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/price_variants/{price-variant-id}/delete

price_variant

always returned
Resource object representing price_variant

Try in API Explorer

This endpoint is used to retrieve a list of price variants.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "price_variant": {
                "updated_at": 1709200385,
                "name": "Germany Berlin",
                "created_at": 1709200385,
                "attributes": [
                    {
                        "name": "country",
                        "value": "germany"
                    },
                    {..}
                ],
                "id": "germany-berlin",
                "external_name": "Germany",
                "resource_version": 1709200385728,
                "status": "active",
                "object": "price_variant"
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/price_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.

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"

status[<operator>]

optional, enumerated string filter
Filter variant based on their status. Possible values are : active, archived
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] = "1243545465"

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"

business_entity_id[<operator>]

optional, string filter
The unique ID of the business entity of this price_variant. 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"

price_variant

always returned
Resource object representing price_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 price variant [ JSON ]

API Index URL

Model Class

Price variant attributes

Consent Fields for Price variant

Custom Fields for Price variant

Create a price variant ¶

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

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

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

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

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