Variant Projections

Variant Projections provide lightweight, read-only representations of individual Product Variants with embedded Product data.

Variant Projections are optimized for use cases such as product detail pages (PDPs) and product listing pages (PLPs) that require Variant-specific data without fetching full Product objects. Each Variant Projection contains the Variant's own data (SKU, key, images, assets, attributes). It also contains Product-level data (name, slug, description).

Variant Projections are automatically created and updated when Variants or their parent Products change.

Projection dimensions

Current and staged

Like Product Projections, Variant Projections support both current (published) and staged (draft) data. Use the staged query parameter to control which representation you retrieve:
  • staged=false (default): returns the current, published representation.
  • staged=true: returns the staged, draft representation.

Locales

You can filter localized fields (name, slug, description, and localized attribute values) to specific locales using the localeProjection query parameter.
For example, localeProjection=en&localeProjection=de returns only the English and German values for localized fields, with other locales omitted from the response.

Prices

When you provide price selection parameters (priceCurrency, priceCountry, priceCustomerGroup, priceChannel), the price field is populated with the best matching price based on the price selection rules.
If no price selection parameters are provided, the price field is absent from the response.

Attributes

The attributes field contains both variant-level and product-level Attributes, merged at projection time. You can filter Attributes in the response using the filter[attributes] query parameter:
  • To include specific Attributes: filter[attributes]=color&filter[attributes]=size
  • To exclude specific Attributes: filter[attributes]=-description&filter[attributes]=-weight

Permissions

  • view_published_products:{projectKey}: required to query current (published) Variant Projections (staged=false).
  • view_products:{projectKey}: required to query staged (draft) Variant Projections (staged=true). This scope implies view_published_products.
  • view_products:{projectKey}:{storeKey}: required to access Variant Projections in the context of a Store.

Representations

VariantProjection

A lightweight, read-only projection of a single Variant with embedded Product data. Variant Projections are automatically created and updated when Variants or their parent Products change.

id
String

Unique identifier of the Variant within its parent Product.

version
Int

Current version of the Variant Projection.

key
String
User-defined unique identifier of the Variant.
staged
Boolean
true for the staged (draft) projection, false for the current (published) projection.
variantId
Int
The id of the Variant.
product
Reference to the parent Product.
name
Name of the parent Product.
slug
Slug of the parent Product.
description
Description of the parent Product.
sku
String
SKU of the Variant.
images
Array of Image
Images of the Variant.
assets
Array of Asset
Assets of the Variant.
attributes
Array of Attribute
Attributes of the Variant, including product-level Attributes merged at projection time.
price
The selected price based on the price selection query parameters. Only present when price selection parameters are provided.
default
Boolean
true if this Variant is the default Variant of its Product (see Product.defaultVariant). false otherwise.
Defaultfalse
createdAt

Date and time (UTC) the Variant Projection was initially created.

VariantProjectionPagedQueryResponse

limit
Int
Default20Minimum0Maximum500
count
Int

Actual number of results returned.

total
Int
Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.
offset
Int
Number of elements skipped.
Default0Maximum10000
results
Array of VariantProjection
VariantProjections matching the query.

Get VariantProjection

Get VariantProjection by ID

GET
https://api.{region}.commercetools.com/{projectKey}/variant-projections/{id}

Retrieves a Variant Projection by its ID.

OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
id
String
Query parameters:
expand
The parameter can be passed multiple times.
staged
Boolean
To retrieve the staged Variant Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false
priceCurrency
Pattern: ^[A-Z]{3}0?$
priceCountry
Enables Product price selection and Scoped Price Search. It can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$
priceCustomerGroup
String
id of an existing CustomerGroup used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceCustomerGroupAssignments
String
IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups. It can be used only in conjunction with the priceCurrency parameter.
The parameter can be passed multiple times.
priceChannel
String
id of an existing Channel used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceRecurrencePolicy
String
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
localeProjection
The parameter can be passed multiple times.
filter[attributes]
String
Specify Attribute names that you want to include or exclude from the response. To exclude an Attribute, add a dash (-) before the Attribute name.
For example, filter[attributes]=color&filter[attributes]=size includes the color and size Attributes. And filter[attributes]=-description&filter[attributes]=-specifications excludes the description and specifications Attributes.

If you specify multiple Attributes to be included and excluded from the response, then the Attributes you want to include are processed before the ones you want to exclude.

The parameter can be passed multiple times.
Response:
200

VariantProjection

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/variant-projections/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: VariantProjectionjson
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "createdAt": "2025-01-01T12:00:00.000Z",
  "staged": false,
  "default": false,
  "variantId": 2,
  "product": {
    "typeId": "product",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "name": {
    "en-US": "Classic T-Shirt",
    "de-DE": "Klassisches T-Shirt",
    "fr-FR": "T-shirt classique",
    "es-ES": "Camiseta clásica"
  },
  "slug": {
    "en-US": "classic-t-shirt",
    "de-DE": "klassisches-t-shirt",
    "fr-FR": "t-shirt-classique",
    "es-ES": "camiseta-clasica"
  },
  "description": {
    "en-US": "A comfortable cotton t-shirt.",
    "de-DE": "Ein bequemes Baumwoll-T-Shirt.",
    "fr-FR": "Un t-shirt en coton confortable.",
    "es-ES": "Una camiseta de algodón cómoda."
  },
  "key": "classic-tshirt-blue-m",
  "sku": "tshirt-blue-m",
  "images": [
    {
      "url": "https://example.com/images/tshirt-blue.jpg",
      "dimensions": {
        "w": 400,
        "h": 400
      }
    }
  ],
  "assets": [],
  "attributes": [
    {
      "name": "color",
      "value": "blue"
    },
    {
      "name": "size",
      "value": "M"
    }
  ]
}

Get VariantProjection by Key

GET
https://api.{region}.commercetools.com/{projectKey}/variant-projections/key={key}

Retrieves a Variant Projection by its key.

OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
key
String
key of the VariantProjection.
Query parameters:
expand
The parameter can be passed multiple times.
staged
Boolean
To retrieve the staged Variant Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false
priceCurrency
Pattern: ^[A-Z]{3}0?$
priceCountry
Enables Product price selection and Scoped Price Search. It can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$
priceCustomerGroup
String
id of an existing CustomerGroup used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceCustomerGroupAssignments
String
IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups. It can be used only in conjunction with the priceCurrency parameter.
The parameter can be passed multiple times.
priceChannel
String
id of an existing Channel used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceRecurrencePolicy
String
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
localeProjection
The parameter can be passed multiple times.
filter[attributes]
String
Specify Attribute names that you want to include or exclude from the response. To exclude an Attribute, add a dash (-) before the Attribute name.
For example, filter[attributes]=color&filter[attributes]=size includes the color and size Attributes. And filter[attributes]=-description&filter[attributes]=-specifications excludes the description and specifications Attributes.

If you specify multiple Attributes to be included and excluded from the response, then the Attributes you want to include are processed before the ones you want to exclude.

The parameter can be passed multiple times.
Response:
200

VariantProjection

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/variant-projections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: VariantProjectionjson
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "createdAt": "2025-01-01T12:00:00.000Z",
  "staged": false,
  "default": false,
  "variantId": 2,
  "product": {
    "typeId": "product",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "name": {
    "en-US": "Classic T-Shirt",
    "de-DE": "Klassisches T-Shirt",
    "fr-FR": "T-shirt classique",
    "es-ES": "Camiseta clásica"
  },
  "slug": {
    "en-US": "classic-t-shirt",
    "de-DE": "klassisches-t-shirt",
    "fr-FR": "t-shirt-classique",
    "es-ES": "camiseta-clasica"
  },
  "description": {
    "en-US": "A comfortable cotton t-shirt.",
    "de-DE": "Ein bequemes Baumwoll-T-Shirt.",
    "fr-FR": "Un t-shirt en coton confortable.",
    "es-ES": "Una camiseta de algodón cómoda."
  },
  "key": "classic-tshirt-blue-m",
  "sku": "tshirt-blue-m",
  "images": [
    {
      "url": "https://example.com/images/tshirt-blue.jpg",
      "dimensions": {
        "w": 400,
        "h": 400
      }
    }
  ],
  "assets": [],
  "attributes": [
    {
      "name": "color",
      "value": "blue"
    },
    {
      "name": "size",
      "value": "M"
    }
  ]
}

Get VariantProjection in Store

Get VariantProjection in Store by ID

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/variant-projections/{id}
Retrieves a Variant Projection by its ID in the specified Store.

Only returns Variants belonging to Products distributed through the Store's configured channels.

Required access scopes:

  • To retrieve the current representation, the view_published_products:{projectKey} scope is required.
  • To retrieve the staged representation, the API Client must have the view_products:{projectKey} scope.
  • To access Variant Projections in the context of a Store, the view_products:{projectKey}:{storeKey} scope is required.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}view_products:{projectKey}:{storeKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
storeKey
String
key of the Store.
id
String
Query parameters:
expand
The parameter can be passed multiple times.
staged
Boolean
To retrieve the staged Variant Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false
priceCurrency
Pattern: ^[A-Z]{3}0?$
priceCountry
Enables Product price selection and Scoped Price Search. It can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$
priceCustomerGroup
String
id of an existing CustomerGroup used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceCustomerGroupAssignments
String
IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups. It can be used only in conjunction with the priceCurrency parameter.
The parameter can be passed multiple times.
priceChannel
String
id of an existing Channel used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceRecurrencePolicy
String
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
localeProjection
The parameter can be passed multiple times.
filter[attributes]
String
Specify Attribute names that you want to include or exclude from the response. To exclude an Attribute, add a dash (-) before the Attribute name.
For example, filter[attributes]=color&filter[attributes]=size includes the color and size Attributes. And filter[attributes]=-description&filter[attributes]=-specifications excludes the description and specifications Attributes.

If you specify multiple Attributes to be included and excluded from the response, then the Attributes you want to include are processed before the ones you want to exclude.

The parameter can be passed multiple times.
Response:
200

VariantProjection

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/variant-projections/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: VariantProjectionjson
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "createdAt": "2025-01-01T12:00:00.000Z",
  "staged": false,
  "default": false,
  "variantId": 2,
  "product": {
    "typeId": "product",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "name": {
    "en-US": "Classic T-Shirt",
    "de-DE": "Klassisches T-Shirt",
    "fr-FR": "T-shirt classique",
    "es-ES": "Camiseta clásica"
  },
  "slug": {
    "en-US": "classic-t-shirt",
    "de-DE": "klassisches-t-shirt",
    "fr-FR": "t-shirt-classique",
    "es-ES": "camiseta-clasica"
  },
  "description": {
    "en-US": "A comfortable cotton t-shirt.",
    "de-DE": "Ein bequemes Baumwoll-T-Shirt.",
    "fr-FR": "Un t-shirt en coton confortable.",
    "es-ES": "Una camiseta de algodón cómoda."
  },
  "key": "classic-tshirt-blue-m",
  "sku": "tshirt-blue-m",
  "images": [
    {
      "url": "https://example.com/images/tshirt-blue.jpg",
      "dimensions": {
        "w": 400,
        "h": 400
      }
    }
  ],
  "assets": [],
  "attributes": [
    {
      "name": "color",
      "value": "blue"
    },
    {
      "name": "size",
      "value": "M"
    }
  ]
}

Get VariantProjection in Store by Key

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/variant-projections/key={key}
Retrieves a Variant Projection by its key in the specified Store.

Only returns Variants belonging to Products distributed through the Store's configured channels.

Required access scopes:

  • To retrieve the current representation, the view_published_products:{projectKey} scope is required.
  • To retrieve the staged representation, the API Client must have the view_products:{projectKey} scope.
  • To access Variant Projections in the context of a Store, the view_products:{projectKey}:{storeKey} scope is required.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}view_products:{projectKey}:{storeKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
storeKey
String
key of the Store.
key
String
key of the VariantProjection.
Query parameters:
expand
The parameter can be passed multiple times.
staged
Boolean
To retrieve the staged Variant Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false
priceCurrency
Pattern: ^[A-Z]{3}0?$
priceCountry
Enables Product price selection and Scoped Price Search. It can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$
priceCustomerGroup
String
id of an existing CustomerGroup used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceCustomerGroupAssignments
String
IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups. It can be used only in conjunction with the priceCurrency parameter.
The parameter can be passed multiple times.
priceChannel
String
id of an existing Channel used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceRecurrencePolicy
String
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
localeProjection
The parameter can be passed multiple times.
filter[attributes]
String
Specify Attribute names that you want to include or exclude from the response. To exclude an Attribute, add a dash (-) before the Attribute name.
For example, filter[attributes]=color&filter[attributes]=size includes the color and size Attributes. And filter[attributes]=-description&filter[attributes]=-specifications excludes the description and specifications Attributes.

If you specify multiple Attributes to be included and excluded from the response, then the Attributes you want to include are processed before the ones you want to exclude.

The parameter can be passed multiple times.
Response:
200

VariantProjection

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/variant-projections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: VariantProjectionjson
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "createdAt": "2025-01-01T12:00:00.000Z",
  "staged": false,
  "default": false,
  "variantId": 2,
  "product": {
    "typeId": "product",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "name": {
    "en-US": "Classic T-Shirt",
    "de-DE": "Klassisches T-Shirt",
    "fr-FR": "T-shirt classique",
    "es-ES": "Camiseta clásica"
  },
  "slug": {
    "en-US": "classic-t-shirt",
    "de-DE": "klassisches-t-shirt",
    "fr-FR": "t-shirt-classique",
    "es-ES": "camiseta-clasica"
  },
  "description": {
    "en-US": "A comfortable cotton t-shirt.",
    "de-DE": "Ein bequemes Baumwoll-T-Shirt.",
    "fr-FR": "Un t-shirt en coton confortable.",
    "es-ES": "Una camiseta de algodón cómoda."
  },
  "key": "classic-tshirt-blue-m",
  "sku": "tshirt-blue-m",
  "images": [
    {
      "url": "https://example.com/images/tshirt-blue.jpg",
      "dimensions": {
        "w": 400,
        "h": 400
      }
    }
  ],
  "assets": [],
  "attributes": [
    {
      "name": "color",
      "value": "blue"
    },
    {
      "name": "size",
      "value": "M"
    }
  ]
}

Query VariantProjections

GET
https://api.{region}.commercetools.com/{projectKey}/variant-projections

Queries Variant Projections matching the provided predicates.

By default, this endpoint returns the current representation where variants are published.

Required access scopes:

  • To retrieve the current representation of published Variants, the view_published_products:{projectKey} scope is required.
  • To retrieve the staged representation (draft data), the API Client must have the view_products:{projectKey} scope.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
Query parameters:
where
The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
Default: 20
Minimum: 0
Maximum: 500
offset
Int
Number of elements skipped.
Default: 0
Maximum: 10000
withTotal
Boolean
Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.
Default: true
staged
Boolean
To retrieve the staged Variant Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false
priceCurrency
Pattern: ^[A-Z]{3}0?$
priceCountry
Enables Product price selection and Scoped Price Search. It can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$
priceCustomerGroup
String
id of an existing CustomerGroup used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceCustomerGroupAssignments
String
IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups. It can be used only in conjunction with the priceCurrency parameter.
The parameter can be passed multiple times.
priceChannel
String
id of an existing Channel used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceRecurrencePolicy
String
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
localeProjection
The parameter can be passed multiple times.
filter[attributes]
String
Specify Attribute names that you want to include or exclude from the response. To exclude an Attribute, add a dash (-) before the Attribute name.
For example, filter[attributes]=color&filter[attributes]=size includes the color and size Attributes. And filter[attributes]=-description&filter[attributes]=-specifications excludes the description and specifications Attributes.

If you specify multiple Attributes to be included and excluded from the response, then the Attributes you want to include are processed before the ones you want to exclude.

The parameter can be passed multiple times.
var.<varName>
String
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/variant-projections -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: VariantProjectionPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 2,
  "total": 2,
  "results": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "createdAt": "2025-01-01T12:00:00.000Z",
      "staged": false,
      "default": false,
      "variantId": 2,
      "product": {
        "typeId": "product",
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      "name": {
        "en-US": "Classic T-Shirt",
        "de-DE": "Klassisches T-Shirt"
      },
      "slug": {
        "en-US": "classic-t-shirt",
        "de-DE": "klassisches-t-shirt"
      },
      "key": "classic-tshirt-blue-m",
      "sku": "tshirt-blue-m",
      "images": [],
      "assets": [
        {
          "id": "a1b2c3d4-asset-0001-0000-000000000001",
          "sources": [
            {
              "uri": "https://example.com/assets/tshirt-blue-m-video.mp4",
              "key": "video",
              "contentType": "video/mp4"
            }
          ],
          "name": {
            "en-US": "Product video",
            "de-DE": "Produktvideo"
          },
          "key": "product-video"
        }
      ],
      "attributes": [
        {
          "name": "color",
          "value": "blue"
        },
        {
          "name": "size",
          "value": "M"
        }
      ]
    },
    {
      "id": "7fb96e12-3456-789a-bcde-f01234567890",
      "version": 1,
      "createdAt": "2025-01-01T12:00:00.000Z",
      "staged": false,
      "default": false,
      "variantId": 3,
      "product": {
        "typeId": "product",
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      "name": {
        "en-US": "Classic T-Shirt",
        "de-DE": "Klassisches T-Shirt"
      },
      "slug": {
        "en-US": "classic-t-shirt",
        "de-DE": "klassisches-t-shirt"
      },
      "key": "classic-tshirt-red-l",
      "sku": "tshirt-red-l",
      "images": [],
      "assets": [
        {
          "id": "a1b2c3d4-asset-0002-0000-000000000002",
          "sources": [
            {
              "uri": "https://example.com/assets/tshirt-red-l-datasheet.pdf",
              "key": "datasheet",
              "contentType": "application/pdf"
            }
          ],
          "name": {
            "en-US": "Size guide",
            "de-DE": "Größentabelle"
          },
          "key": "size-guide"
        }
      ],
      "attributes": [
        {
          "name": "color",
          "value": "red"
        },
        {
          "name": "size",
          "value": "L"
        }
      ]
    }
  ]
}

Query VariantProjections in Store

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/variant-projections
Queries Variant Projections in the specified Store.
Only Variants belonging to Products distributed through the Store's configured channels are returned. By default, this endpoint returns the current representation of Variants where the published flag is true.

Required access scopes:

  • To retrieve the current representation of published Variants, the view_published_products:{projectKey} scope is required.
  • To retrieve the staged representation, the API Client must have the view_products:{projectKey} scope.
  • To access Variant Projections in the context of a Store, the view_products:{projectKey}:{storeKey} scope is required.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}view_products:{projectKey}:{storeKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
storeKey
String
key of the Store.
Query parameters:
where
The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
Default: 20
Minimum: 0
Maximum: 500
offset
Int
Number of elements skipped.
Default: 0
Maximum: 10000
withTotal
Boolean
Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.
Default: true
staged
Boolean
To retrieve the staged Variant Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false
priceCurrency
Pattern: ^[A-Z]{3}0?$
priceCountry
Enables Product price selection and Scoped Price Search. It can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$
priceCustomerGroup
String
id of an existing CustomerGroup used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceCustomerGroupAssignments
String
IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups. It can be used only in conjunction with the priceCurrency parameter.
The parameter can be passed multiple times.
priceChannel
String
id of an existing Channel used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceRecurrencePolicy
String
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
localeProjection
The parameter can be passed multiple times.
filter[attributes]
String
Specify Attribute names that you want to include or exclude from the response. To exclude an Attribute, add a dash (-) before the Attribute name.
For example, filter[attributes]=color&filter[attributes]=size includes the color and size Attributes. And filter[attributes]=-description&filter[attributes]=-specifications excludes the description and specifications Attributes.

If you specify multiple Attributes to be included and excluded from the response, then the Attributes you want to include are processed before the ones you want to exclude.

The parameter can be passed multiple times.
var.<varName>
String
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/variant-projections -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: VariantProjectionPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 2,
  "total": 2,
  "results": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "createdAt": "2025-01-01T12:00:00.000Z",
      "staged": false,
      "default": false,
      "variantId": 2,
      "product": {
        "typeId": "product",
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      "name": {
        "en-US": "Classic T-Shirt",
        "de-DE": "Klassisches T-Shirt"
      },
      "slug": {
        "en-US": "classic-t-shirt",
        "de-DE": "klassisches-t-shirt"
      },
      "key": "classic-tshirt-blue-m",
      "sku": "tshirt-blue-m",
      "images": [],
      "assets": [
        {
          "id": "a1b2c3d4-asset-0001-0000-000000000001",
          "sources": [
            {
              "uri": "https://example.com/assets/tshirt-blue-m-video.mp4",
              "key": "video",
              "contentType": "video/mp4"
            }
          ],
          "name": {
            "en-US": "Product video",
            "de-DE": "Produktvideo"
          },
          "key": "product-video"
        }
      ],
      "attributes": [
        {
          "name": "color",
          "value": "blue"
        },
        {
          "name": "size",
          "value": "M"
        }
      ]
    },
    {
      "id": "7fb96e12-3456-789a-bcde-f01234567890",
      "version": 1,
      "createdAt": "2025-01-01T12:00:00.000Z",
      "staged": false,
      "default": false,
      "variantId": 3,
      "product": {
        "typeId": "product",
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      "name": {
        "en-US": "Classic T-Shirt",
        "de-DE": "Klassisches T-Shirt"
      },
      "slug": {
        "en-US": "classic-t-shirt",
        "de-DE": "klassisches-t-shirt"
      },
      "key": "classic-tshirt-red-l",
      "sku": "tshirt-red-l",
      "images": [],
      "assets": [
        {
          "id": "a1b2c3d4-asset-0002-0000-000000000002",
          "sources": [
            {
              "uri": "https://example.com/assets/tshirt-red-l-datasheet.pdf",
              "key": "datasheet",
              "contentType": "application/pdf"
            }
          ],
          "name": {
            "en-US": "Size guide",
            "de-DE": "Größentabelle"
          },
          "key": "size-guide"
        }
      ],
      "attributes": [
        {
          "name": "color",
          "value": "red"
        },
        {
          "name": "size",
          "value": "L"
        }
      ]
    }
  ]
}

Check if VariantProjection exists

Check if VariantProjection exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/variant-projections/{id}
Checks if a VariantProjection exists with the provided id. Returns a 200 status if the VariantProjection exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
id
String
Query parameters:
staged
Boolean
To retrieve the staged Variant Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false
priceCurrency

Validated for consistency with the GET endpoint but does not affect the existence check.

Pattern: ^[A-Z]{3}0?$
priceCountry
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$
priceCustomerGroup
String
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
priceChannel
String
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
localeProjection

Validated for consistency with the GET endpoint but does not affect the existence check.

The parameter can be passed multiple times.
filter[attributes]
String

Validated for consistency with the GET endpoint but does not affect the existence check.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/variant-projections/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if VariantProjection exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/variant-projections/key={key}
Checks if a VariantProjection exists with the provided key. Returns a 200 status if the VariantProjection exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
key
String
key of the VariantProjection.
Query parameters:
staged
Boolean
To retrieve the staged Variant Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false
priceCurrency

Validated for consistency with the GET endpoint but does not affect the existence check.

Pattern: ^[A-Z]{3}0?$
priceCountry
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$
priceCustomerGroup
String
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
priceChannel
String
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
localeProjection

Validated for consistency with the GET endpoint but does not affect the existence check.

The parameter can be passed multiple times.
filter[attributes]
String

Validated for consistency with the GET endpoint but does not affect the existence check.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/variant-projections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if VariantProjection exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/variant-projections
Checks if a Variant Projection exists for the provided query predicate. Returns a 200 status if any Variant Projections match, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
Query parameters:
where
The parameter can be passed multiple times.
staged
Boolean
To retrieve the staged Variant Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false
priceCurrency

Validated for consistency with the GET endpoint but does not affect the existence check.

Pattern: ^[A-Z]{3}0?$
priceCountry
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$
priceCustomerGroup
String
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
priceChannel
String
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
localeProjection

Validated for consistency with the GET endpoint but does not affect the existence check.

The parameter can be passed multiple times.
filter[attributes]
String

Validated for consistency with the GET endpoint but does not affect the existence check.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/variant-projections -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if VariantProjection exists in Store

Check if VariantProjection exists in Store by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/variant-projections/{id}
Checks if a Variant Projection exists with the provided id in the specified Store. Returns a 200 status if the Variant Projection exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}view_products:{projectKey}:{storeKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
storeKey
String
key of the Store.
id
String
Query parameters:
staged
Boolean
To retrieve the staged Variant Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false
priceCurrency

Validated for consistency with the GET endpoint but does not affect the existence check.

Pattern: ^[A-Z]{3}0?$
priceCountry
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$
priceCustomerGroup
String
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
priceChannel
String
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
localeProjection

Validated for consistency with the GET endpoint but does not affect the existence check.

The parameter can be passed multiple times.
filter[attributes]
String

Validated for consistency with the GET endpoint but does not affect the existence check.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/variant-projections/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if VariantProjection exists in Store by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/variant-projections/key={key}
Checks if a Variant Projection exists with the provided key in the specified Store. Returns a 200 status if the Variant Projection exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}view_products:{projectKey}:{storeKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
storeKey
String
key of the Store.
key
String
key of the VariantProjection.
Query parameters:
staged
Boolean
To retrieve the staged Variant Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false
priceCurrency

Validated for consistency with the GET endpoint but does not affect the existence check.

Pattern: ^[A-Z]{3}0?$
priceCountry
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$
priceCustomerGroup
String
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
priceChannel
String
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
localeProjection

Validated for consistency with the GET endpoint but does not affect the existence check.

The parameter can be passed multiple times.
filter[attributes]
String

Validated for consistency with the GET endpoint but does not affect the existence check.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/variant-projections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if VariantProjection exists in Store by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/variant-projections
Checks if one or more Variant Projections exist for the provided query predicate in the specified Store. Returns a 200 status if any Variant Projections match, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}view_products:{projectKey}:{storeKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
storeKey
String
key of the Store.
Query parameters:
where
The parameter can be passed multiple times.
staged
Boolean
To retrieve the staged Variant Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false
priceCurrency

Validated for consistency with the GET endpoint but does not affect the existence check.

Pattern: ^[A-Z]{3}0?$
priceCountry
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$
priceCustomerGroup
String
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
priceChannel
String
Validated for consistency with the GET endpoint. Can be used only in conjunction with the priceCurrency parameter.
localeProjection

Validated for consistency with the GET endpoint but does not affect the existence check.

The parameter can be passed multiple times.
filter[attributes]
String

Validated for consistency with the GET endpoint but does not affect the existence check.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/variant-projections -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"