Variant Groups

View as Markdown

Variants in Contentstack provides an overview of variant groups and linked content types, which are used for content personalization. Linking content types to variant groups allows you to create entry variants.

A variant group is a collection of variants that share the same set of linked content types. Every variant belongs to a variant group and inherits the content types linked to that group, which is what makes the variant available on entries of those content types.

Note

The Variants feature may not be available by default to all organizations. Reach out to our support team to get it enabled.
When a variant group is linked to a Personalize experience, Personalize owns the group name, its variants, and the personalize_metadata object. Those properties are read-only through the Content Management API, and you cannot delete a linked variant group or variant until you delete the corresponding experience or variation in Personalize.

Create variant group

POSThttps://api.contentstack.io/v3/variant_groups

The Create variant group request lets you create a variant group in your stack. A variant group is a collection of variants that share the same set of linked content types, and every variant that you create inside the group inherits those content types.

In the “Body” section, pass the following parameters:

name (required): Enter a unique name for your variant group.
uid (optional): Enter a custom unique ID for your variant group. You cannot change this value later.
description (optional): Enter a description for your variant group.
content_types (optional): An array of content type UIDs to link to the variant group.

Note

The Variants feature is currently available as part of an Early Access Program and may not be available to all users. For more information, you can reach out to our support team.
If you do not pass the content_types parameter, Contentstack links all the content types in your stack to the variant group.
If you do not pass a uid, Contentstack generates one for you. You cannot change the UID after you create the variant group.

Sample Request

{
    "name": "Variant-Group-1",
    "description": "Regional variants for product pages",
    "content_types": [
        "mobile",
        "laptop"
    ]
}

Sample Response

Status|201 Created

{
    "name": "Variant-Group-1",
    "description": "Regional variants for product pages",
    "uid": "cs**************43",
    "content_types": [
        {
            "uid": "mobile",
            "status": "linked"
        },
        {
            "uid": "laptop",
            "status": "linked"
        }
    ],
    "branches": [
        "main"
    ],
    "created_by": "blt**************59",
    "updated_by": "blt**************59",
    "created_at": "2026-08-25T10:00:00.000Z",
    "updated_at": "2026-08-25T10:00:00.000Z"
}

Get all variant groups

GET

https://api.contentstack.io/v3/variant_groups?skip=0&limit=30&include_count=true&include_variant_info=true&include_variant_count=true&desc=created_at&content_type={your_content_type_uid}

The Get all variant groups request returns a list of all variant groups linked to your stack. To retrieve the variant UIDs specific to a content type, include the content_type query parameter with the content type UID in your request.

Sample Response

Status|200 OK

{
    "variant_groups": [
        {
            "name": "region",
            "created_by": "blt**************59",
            "updated_by": "blt**************59",
            "uid": "cs**************43",
            "branches": [
                "main"
            ],
            "content_types": [
                {
                    "uid": "mobile",
                    "status": "linked"
                },
                {
                    "uid": "laptop",
                    "status": "linked"
                }
            ],
            "created_at": "2024-08-20T10:31:07.092Z",
            "updated_at": "2024-08-20T10:31:07.092Z"
        },
        {
            "name": "Variant-Group-test-ct",
            "created_by": "blt**************9e",
            "updated_by": "blt**************33",
            "uid": "cs8**************b6",
            "content_types": [
                {
                    "uid": "testing_variant_cases",
                    "status": "linked"
                },
                {
                    "uid": "test_reference",
                    "status": "linked"
                },
                {
                    "uid": "test",
                    "status": "linked"
                }
            ],
            "created_at": "2024-08-21T10:10:29.494Z",
            "updated_at": "2024-08-22T11:30:48.669Z",
            "description": "",
            "variant_count": 3,
            "variants": [
                {
                    "uid": "cs1**************67",
                    "created_by": "blt**************33",
                    "updated_by": "blt**************33",
                    "name": "test",
                    "created_at": "2024-08-22T11:30:48.774Z",
                    "updated_at": "2024-08-22T11:30:48.774Z"
                },
                {
                    "uid": "cs3**************8f",
                    "created_by": "blt**************33",
                    "updated_by": "blt**************33",
                    "name": "test 2",
                    "created_at": "2024-08-22T11:30:48.978Z",
                    "updated_at": "2024-08-22T11:30:48.978Z"
                },
                {
                    "uid": "cs3d901397291171c0",
                    "created_by": "blt**************33",
                    "updated_by": "blt**************33",
                    "name": "test 3",
                    "created_at": "2024-08-22T11:30:48.979Z",
                    "updated_at": "2024-08-22T11:30:48.979Z"
                }
            ]
        },
        {
            "content_types": [
                {
                    "uid": "vigor",
                    "status": "linked"
                },
                {
                    "uid": "tsyuio",
                    "status": "linked"
                }
            ],
            "name": "test segmentated",
            "personalize_metadata": {
                "project_uid": "660bc**************31ac",
                "experience_uid": "660bd**************431ba",
                "experience_short_uid": "0",
                "status": "linked"
            },
            "created_by": null,
            "updated_by": "blt**************1a",
            "uid": "cse**************e2",
            "created_at": "2024-08-22T11:41:36.588Z",
            "updated_at": "2024-08-22T13:07:10.907Z",
            "variant_count": 2,
            "variants": [
                {
                    "uid": "csf**************7d",
                    "created_by": null,
                    "updated_by": "blt**************1a",
                    "name": "Country",
                    "variant_group_uid": "cse**************e2",
                    "personalize_metadata": {
                        "project_uid": "660bc**************31ac",
                        "experience_uid": "660bd**************31ba",
                        "experience_short_uid": "0",
                        "status": "linked",
                        "variant_short_uid": "1"
                    },
                    "alias": "cs_personalize_0_1",
                    "created_at": "2024-08-22T11:41:36.602Z",
                    "updated_at": "2024-08-22T13:07:11.069Z"
                },
                {
                    "uid": "cs8**************5e",
                    "created_by": null,
                    "updated_by": "blt**************1a",
                    "name": "test",
                    "variant_group_uid": "cse**************e2",
                    "personalize_metadata": {
                        "project_uid": "660bc**************31ac",
                        "experience_uid": "660bd**************31ba",
                        "experience_short_uid": "0",
                        "status": "linked",
                        "variant_short_uid": "0"
                    },
                    "alias": "cs_personalize_0_0",
                    "created_at": "2024-08-22T11:41:36.603Z",
                    "updated_at": "2024-08-22T13:07:11.088Z"
                }
            ]
        }
    ]
}

Update variant group

PUThttps://api.contentstack.io/v3/variant_groups/{variant_group_uid}

The Update variant group request lets you rename a variant group, change its description, and link or unlink content types. Pass at least one of the body parameters below.

In the “Body” section, pass the following parameters:

name (optional): Enter a new unique name for your variant group.
description (optional): Enter a new description for your variant group.
content_types (optional): An array of objects, each identifying one content type through its uid and its link status. Set the status to either linked or unlinked.

Unlinking a content type does not delete the entry variants that already exist for it, but it does prevent you from creating new entry variants for that content type.

Note

The Variants feature is currently available as part of an Early Access Program and may not be available to all users. For more information, you can reach out to our support team.
You cannot change the uid of a variant group after you create it.
The personalize_metadata object is managed by Personalize and is read-only through the Content Management API.

Sample Request

{
    "name": "Variant-Group-1-Updated",
    "content_types": [
        {
            "uid": "mobile",
            "status": "linked"
        },
        {
            "uid": "laptop",
            "status": "unlinked"
        }
    ]
}

Sample Response

Status|200 OK

{
    "name": "Variant-Group-1-Updated",
    "uid": "cs**************43",
    "content_types": [
        {
            "uid": "mobile",
            "status": "linked"
        },
        {
            "uid": "laptop",
            "status": "unlinked"
        }
    ],
    "branches": [
        "main"
    ],
    "created_by": "blt**************59",
    "updated_by": "blt**************33",
    "created_at": "2026-08-25T10:00:00.000Z",
    "updated_at": "2026-08-25T10:20:00.000Z"
}

Delete variant group

DELETEhttps://api.contentstack.io/v3/variant_groups/{variant_group_uid}

The Delete variant group request lets you delete a variant group from your stack.

WarningDeleting a variant group also deletes every variant inside that group. The entry variants that belong to those variants are unpublished and removed from your entries.

Note

The Variants feature is currently available as part of an Early Access Program and may not be available to all users. For more information, you can reach out to our support team.
You cannot delete a variant group while it is linked to a Personalize experience. Delete the experience in Personalize first, which unlinks the variant group and makes it available for deletion.

Sample Response

Status|200 OK

{
    "notice": "Variant group deleted successfully."
}

Link content types

PUThttps://api.contentstack.io/v3/variant_groups/{variant_group_uid}/variants

The Link content types request allows you to link content types to your variant group.

In the “Body” section, enter the content type UID(s) in the following format:

        {
            "uid": "content_type_uid_1",
            "status": "linked"
        },
        {
            "uid": "content_type_uid_2",
            "status": "linked"
        }

Sample Request

{
    "content_types": [
        {
            "uid": "content_type_uid_1",
            "status": "linked"
        },
        {
            "uid": "content_type_uid_2",
            "status": "linked"
        }
    ],
    "uid": "csd**************03",
    "branches": [
        "main"
    ]
}

Sample Response

Status|200 OK

{
    "content_types": [
        {
            "uid": "content_type_uid_1",
            "status": "linked"
        },
        {
            "uid": "content_type_uid_2",
            "status": "linked"
        }
    ],
    "name": "Variant-Group-Name",
    "personalize_metadata": {
        "project_uid": "660bc**************31ac",
        "experience_uid": "660bd**************31ba",
        "experience_short_uid": "0",
        "status": "linked"
    },
    "created_by": "blt**************9e",
    "updated_by": "blt**************1a",
    "uid": "csd**************03",
    "created_at": "2024-05-22T05:56:15.393Z",
    "updated_at": "2024-09-06T09:04:19.758Z",
    "message": "Variant Group and Variants updated successfully",
    "variants": []
}

Unlink content types

PUThttps://api.contentstack.io/v3/variant_groups/{variant_group_uid}/variants

The Unlink content types request allows you to unlink content types to your variant group.

In the “Body” section, enter the content type UID(s) in the following format:

        {
            "uid": "content_type_uid_1",
            "status": "unlinked"
        },
        {
            "uid": "content_type_uid_2",
            "status": "unlinked"
        }

Sample Request

{
    "content_types": [
        {
            "uid": "content_type_uid_1",
            "status": "unlinked"
        },
        {
            "uid": "content_type_uid_2",
            "status": "unlinked"
        }
    ],
    "uid": "csd**************03",
    "branches": [
        "main"
    ]
}

Sample Response

Status|200 OK

{
    "content_types": [
        {
            "uid": "content_type_uid_1",
            "status": "unlinked"
        },
        {
            "uid": "content_type_uid_2",
            "status": "unlinked"
        }
    ],
    "name": "Variant-Group-Name",
    "personalize_metadata": {
        "project_uid": "660bc**************31ac",
        "experience_uid": "660bd**************31ba",
        "experience_short_uid": "0",
        "status": "linked"
    },
    "created_by": "blt**************9e",
    "updated_by": "blt**************1a",
    "uid": "csd**************03",
    "created_at": "2024-05-22T05:56:15.393Z",
    "updated_at": "2024-09-06T09:04:19.758Z",
    "message": "Variant Group and Variants updated successfully",
    "variants": []
}

Create variant

POSThttps://api.contentstack.io/v3/variant_groups/{variant_group_uid}/variants

The Create variant request lets you create a variant inside an existing variant group. The variant inherits every content type linked to that group, which makes it available on entries of those content types.

In the “Body” section, pass the following parameters:

name (required): Enter a name for your variant. The name must be unique within the variant group.
uid (optional): Enter a custom unique ID for your variant. You cannot change this value later.

Note

The Variants feature is currently available as part of an Early Access Program and may not be available to all users. For more information, you can reach out to our support team.
Contentstack recommends that you pass a custom uid, because you use this UID later to fetch and customize entry variants. If you omit it, Contentstack generates one for you.
To create a variant that does not belong to any variant group, send the same request body to POST /variants instead.

Sample Request

{
    "uid": "region_north_america",
    "name": "North America"
}

Sample Response

Status|201 Created

{
    "uid": "region_north_america",
    "name": "North America",
    "variant_group_uid": "cs**************43",
    "branches": [
        "main"
    ],
    "created_by": "blt**************59",
    "updated_by": "blt**************59",
    "created_at": "2026-08-25T10:05:00.000Z",
    "updated_at": "2026-08-25T10:05:00.000Z"
}

Get all variants in a variant group

GET

https://api.contentstack.io/v3/variant_groups/{variant_group_uid}/variants?skip=0&limit=30&include_count=true&desc=created_at

The Get all variants in a variant group request returns the variant group along with every variant that belongs to it.

NoteThe Variants feature is currently available as part of an Early Access Program and may not be available to all users. For more information, you can reach out to our support team.

Sample Response

Status|200 OK

{
    "uid": "cs**************43",
    "name": "Variant-Group-1",
    "content_types": [
        {
            "uid": "mobile",
            "status": "linked"
        }
    ],
    "variants": [
        {
            "uid": "region_north_america",
            "name": "North America",
            "created_by": "blt**************59",
            "updated_by": "blt**************59",
            "created_at": "2026-08-25T10:05:00.000Z",
            "updated_at": "2026-08-25T10:05:00.000Z"
        },
        {
            "uid": "region_europe",
            "name": "Europe",
            "created_by": "blt**************59",
            "updated_by": "blt**************59",
            "created_at": "2026-08-25T10:06:00.000Z",
            "updated_at": "2026-08-25T10:06:00.000Z"
        }
    ],
    "count": 2
}

Get single variant

GEThttps://api.contentstack.io/v3/variants/{variant_uid}

The Get single variant request returns the details of a specific variant. If the variant belongs to a variant group, the response also includes a summary of that group under variant_group.

To fetch several variants in one call, pass the uids query parameter once for each variant, for example /variants?uids=cs**************43&uids=cs**************5e. The response then returns the matching variants in a variants array.

NoteThe Variants feature is currently available as part of an Early Access Program and may not be available to all users. For more information, you can reach out to our support team.

Sample Response

Status|200 OK

{
    "uid": "region_north_america",
    "name": "North America",
    "created_by": "blt**************59",
    "updated_by": "blt**************59",
    "created_at": "2026-08-25T10:05:00.000Z",
    "updated_at": "2026-08-25T10:05:00.000Z",
    "variant_group": {
        "uid": "cs**************43",
        "name": "Variant-Group-1",
        "content_types": [
            {
                "uid": "mobile",
                "status": "linked"
            }
        ]
    }
}

Update variant

PUThttps://api.contentstack.io/v3/variants/{variant_uid}

The Update variant request lets you rename a variant. The name is the only property of a variant that you can change.

In the “Body” section, pass the name parameter (required) with a new name for your variant. The name must be unique within the variant group.

Note

The Variants feature is currently available as part of an Early Access Program and may not be available to all users. For more information, you can reach out to our support team.
You cannot change the uid of a variant after you create it.
To scope the request to a variant group, use /variant_groups/{variant_group_uid}/variants/{variant_uid} instead. Contentstack then returns an error if the variant does not belong to that group.

Sample Request

{
    "name": "North America - East"
}

Sample Response

Status|200 OK

{
    "uid": "region_north_america",
    "name": "North America - East",
    "variant_group_uid": "cs**************43",
    "branches": [
        "main"
    ],
    "created_by": "blt**************59",
    "updated_by": "blt**************33",
    "created_at": "2026-08-25T10:05:00.000Z",
    "updated_at": "2026-08-25T10:22:00.000Z"
}

Delete variant

DELETEhttps://api.contentstack.io/v3/variants/{variant_uid}

The Delete variant request lets you delete a single variant without deleting the variant group it belongs to.

WarningDeleting a variant unpublishes and removes the entry variants that editors created for it.

Note

The Variants feature is currently available as part of an Early Access Program and may not be available to all users. For more information, you can reach out to our support team.
You cannot delete a variant while it is linked to a variation in a Personalize experience. Delete the variation in Personalize first, which unlinks the variant and makes it available for deletion.
To scope the request to a variant group, use /variant_groups/{variant_group_uid}/variants/{variant_uid} instead. Contentstack then returns an error if the variant does not belong to that group.

Sample Response

Status|200 OK

{
    "notice": "Variant deleted successfully."
}

Variant Groups

Create variant group

Get all variant groups

Update variant group

Delete variant group

Link content types

Unlink content types

Create variant

Get all variants in a variant group

Get single variant

Update variant

Delete variant

Variant Groups

Create variant group

Headers

Get all variant groups

Query Parameters

Headers

Update variant group

URL Parameters

Headers

Delete variant group

URL Parameters

Headers

Link content types

URL Parameters

Headers

Unlink content types

URL Parameters

Headers

Create variant

URL Parameters

Headers

Get all variants in a variant group

URL Parameters

Query Parameters

Headers

Get single variant

URL Parameters

Query Parameters

Headers

Update variant

URL Parameters

Headers

Delete variant

URL Parameters

Headers

Headers

Query Parameters

Headers

URL Parameters

Headers

URL Parameters

Headers

URL Parameters

Headers

URL Parameters

Headers

URL Parameters

Headers

URL Parameters

Query Parameters

Headers

URL Parameters

Query Parameters

Headers

URL Parameters

Headers

URL Parameters

Headers