VariantGroups
VariantGroups
The VariantGroup class lists the variant groups of a stack, and links content types to a variant group or unlinks them.
When to Use This Class: Use this class before you create entry variants. A content type needs a link to a variant group before its entries can have variants of that group.
Conceptual Role: Acts as the Content Management API (CMA) client for the /variant_groups endpoint. Call stack.VariantGroup() to get an instance.
Returns: VariantGroup. A handle for variant group operations.
Instance State
The UID you pass to stack.VariantGroup() decides which methods you can call on the instance:
- Call stack.VariantGroup() without a UID to list variant groups with Find or FindAsync.
- Call stack.VariantGroup("<VARIANT_GROUP_UID>") to work with one group, for example LinkContentTypes or UnlinkContentTypes.
If you call a method from the other group, it throws InvalidOperationException before any request leaves the SDK. The Method Index below lists every method in each group.
Warning The SDK checks for an empty string as if it were no UID, so stack.VariantGroup("") allows Find, and the request path then ends in /variant_groups/. Call stack.VariantGroup() with no argument when you mean the list.
Class-Level Notes
Getting an instance.
- stack.VariantGroup() throws InvalidOperationException when the client has no authtoken and the stack has no management token, or when the stack has no API key.
- The Uid property of an instance has no public setter. Call stack.VariantGroup() again to work with another group.
What a variant group does.
- A variant group holds variants that share the same linked content types. Each variant in the group becomes available on entries of those content types.
- The CMA reference notes that the variants feature may not be available to every organization. See Variant Groups.
- Use the EntryVariant class to create the variant content of an entry after you link its content type.
Errors.
- The SDK throws ContentstackErrorException when the API returns an error status. Read StatusCode, ErrorCode, ErrorMessage, and Errors on the exception to see what the API rejected.
Rate Limiting & Retry.
- This SDK automatically retries a request that returns 429, 500, 502, 503, or 504, with configurable delay and attempt limits.
Additional Resources Refer to Retry Mechanism to configure retries, and Content Management API Errors for the error codes the API returns.
Async methods.
- An async method runs its client-side checks when you call it, before it returns a task. An API rejection surfaces when you await the task.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Create, rename, or delete a variant group | No | The CMA has these requests, and this SDK has no method for them. |
| Create, list, update, or delete the variants of a group | No | The CMA has these requests, and this SDK has no method for them. |
| Fetch one variant group | No | Call Find and read the group from the list. |
Method Index
List variant groups. Available on stack.VariantGroup() when you pass no UID.
| Method Name | Returns | Description |
|---|---|---|
| Find | The API response with the variant groups. | Lists the variant groups of the stack. |
| FindAsync | The API response with the variant groups. | Lists the variant groups asynchronously. |
Link and unlink content types. Available on stack.VariantGroup("<VARIANT_GROUP_UID>").
| Method Name | Returns | Description |
|---|---|---|
| LinkContentTypes | The API response with the updated variant group. | Links content types to the group. |
| LinkContentTypesAsync | The API response with the updated variant group. | Links content types asynchronously. |
| UnlinkContentTypes | The API response with the updated variant group. | Unlinks content types from the group. |
| UnlinkContentTypesAsync | The API response with the updated variant group. | Unlinks content types asynchronously. |
Class-Level Snippet
The snippet below lists the variant groups of a stack and links one content type to a group.
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");
try
{
ContentstackResponse groups = await stack.VariantGroup().FindAsync();
Console.WriteLine(groups.OpenJsonObjectResponse().ToJsonString());
List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>" };
await stack.VariantGroup("<VARIANT_GROUP_UID>").LinkContentTypesAsync(contentTypeUids);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects a request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Methods
Each method of the VariantGroup class has its own section below, with its parameters, validation rules, behavior, and examples.
Find
Find lists the variant groups of the stack.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Query parameters, for example include_variant_info. |
Returns: ContentstackResponse. The API response with the variant groups.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has a UID, because Find lists every group. Call stack.VariantGroup() with no UID.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one GET request to /variant_groups, with the entries of collection as query parameters.
- The Content Management API (CMA) reference lists the query parameters below for this request. See Get all variant groups.
- skip and limit: the page of groups to return.
- include_count, include_variant_info, and include_variant_count: the total, the variants, and the variant count of each group.
- asc and desc: the sort order, by created_at or name.
- content_type: only the groups linked to that content type UID.
- Does not page through the results for you. Without limit and skip, the API applies its own page size.
- Returns the raw API response.
Example
Basic usage: list the variant groups of a stack
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").VariantGroup().Find();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: list the groups of one content type with their variants
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("content_type", "<CONTENT_TYPE_UID>");
collection.Add("include_variant_info", true);
collection.Add("include_count", true);
collection.Add("desc", "created_at");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").VariantGroup().Find(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Management token: list the variant groups
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient();
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").VariantGroup().Find();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}FindAsync
FindAsync lists the variant groups of the stack, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Query parameters, for example include_variant_info. |
Returns: Task<ContentstackResponse>. The API response with the variant groups.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has a UID, because FindAsync lists every group.
- The SDK throws the exceptions above when you call FindAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Behaves like Find.
Example
Basic usage: list the variant groups of a stack
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").VariantGroup().FindAsync();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: read the first 10 groups with their variant counts
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("limit", 10);
collection.Add("include_variant_count", true);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").VariantGroup().FindAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}LinkContentTypes
LinkContentTypes links the content types you list to the variant group whose UID you passed to stack.VariantGroup().
| Name | Type | Description |
|---|---|---|
| contentTypeUids (required) | List<string> | Content type UIDs to link. |
| collection | ParameterCollection? | Query parameters for the request. |
Returns: ContentstackResponse. The API response with the updated variant group.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no UID, because the request path names the group. Call stack.VariantGroup("<VARIANT_GROUP_UID>").
- Throws ArgumentNullException (parameter contentTypeUids) if contentTypeUids is null or empty, because the request needs at least one content type.
- The SDK does not check that each UID names a content type. The API rejects a UID that does not.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one PUT request to /variant_groups/<VARIANT_GROUP_UID>/variants. See Link content types in the Content Management API (CMA) reference.
- Builds the body from your list:
- content_types: one object per UID, with status set to linked.
- uid: the variant group UID.
- branches: always ["main"], whatever branch the Stack targets.
- Sends the entries of collection as query parameters.
- Returns the raw API response.
Example
Basic usage: link a content type to a variant group
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>" };
try
{
ContentstackResponse response = client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").LinkContentTypes(contentTypeUids);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: link two content types with a query parameter collection
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>", "<SECOND_CONTENT_TYPE_UID>" };
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").LinkContentTypes(contentTypeUids, collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: passing an empty list
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").LinkContentTypes(new List<string>());
}
catch (ArgumentNullException e)
{
// Thrown before any request because the list holds no content type UID
Console.WriteLine(e.ParamName);
}LinkContentTypesAsync
LinkContentTypesAsync links the content types you list to the variant group whose UID you passed to stack.VariantGroup(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| contentTypeUids (required) | List<string> | Content type UIDs to link. |
| collection | ParameterCollection? | Query parameters for the request. |
Returns: Task<ContentstackResponse>. The API response with the updated variant group.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no UID, because the request path names the group.
- Throws ArgumentNullException (parameter contentTypeUids) if contentTypeUids is null or empty.
- The SDK throws the exceptions above when you call LinkContentTypesAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Behaves like LinkContentTypes.
Example
Basic usage: link a content type to a variant group
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>" };
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").LinkContentTypesAsync(contentTypeUids);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: link two content types with a management token
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>", "<SECOND_CONTENT_TYPE_UID>" };
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.VariantGroup("<VARIANT_GROUP_UID>")
.LinkContentTypesAsync(contentTypeUids, collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}UnlinkContentTypes
UnlinkContentTypes unlinks the content types you list from the variant group whose UID you passed to stack.VariantGroup().
| Name | Type | Description |
|---|---|---|
| contentTypeUids (required) | List<string> | Content type UIDs to unlink. |
| collection | ParameterCollection? | Query parameters for the request. |
Returns: ContentstackResponse. The API response with the updated variant group.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no UID, because the request path names the group. Call stack.VariantGroup("<VARIANT_GROUP_UID>").
- Throws ArgumentNullException (parameter contentTypeUids) if contentTypeUids is null or empty, because the request needs at least one content type.
- The SDK does not check that each UID names a content type. The API rejects a UID that does not.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one PUT request to /variant_groups/<VARIANT_GROUP_UID>/variants. See Unlink content types in the Content Management API (CMA) reference.
- Builds the body from your list:
- content_types: one object per UID, with status set to unlinked.
- uid: the variant group UID.
- branches: always ["main"], whatever branch the Stack targets.
- Sends the entries of collection as query parameters.
- Returns the raw API response.
Example
Basic usage: unlink a content type from a variant group
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>" };
try
{
ContentstackResponse response = client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").UnlinkContentTypes(contentTypeUids);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: unlink two content types with a query parameter collection
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>", "<SECOND_CONTENT_TYPE_UID>" };
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").UnlinkContentTypes(contentTypeUids, collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: passing an empty list
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").UnlinkContentTypes(new List<string>());
}
catch (ArgumentNullException e)
{
// Thrown before any request because the list holds no content type UID
Console.WriteLine(e.ParamName);
}UnlinkContentTypesAsync
UnlinkContentTypesAsync unlinks the content types you list from the variant group whose UID you passed to stack.VariantGroup(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| contentTypeUids (required) | List<string> | Content type UIDs to unlink. |
| collection | ParameterCollection? | Query parameters for the request. |
Returns: Task<ContentstackResponse>. The API response with the updated variant group.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no UID, because the request path names the group.
- Throws ArgumentNullException (parameter contentTypeUids) if contentTypeUids is null or empty.
- The SDK throws the exceptions above when you call UnlinkContentTypesAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Behaves like UnlinkContentTypes.
Example
Basic usage: unlink a content type from a variant group
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>" };
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").UnlinkContentTypesAsync(contentTypeUids);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: unlink two content types with a management token
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>", "<SECOND_CONTENT_TYPE_UID>" };
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.VariantGroup("<VARIANT_GROUP_UID>")
.UnlinkContentTypesAsync(contentTypeUids, collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}