Variant Projections

B2CB2BB2XBETA

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). These pages require variant-level data without fetching full Product objects. Each Variant Projection contains variant-level data (SKU, key, images, assets, attributes). It also contains product-level data (name, slug, description, categories, and categoryOrderHints).

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

Tailoring

In-store Variant Projections support Product Tailoring. When a Product Tailoring exists for a Product and Store, the in-store endpoints apply Variant Tailoring and return the tailored Product name, slug, and description, along with the tailored Variant images, assets, and attributes. The staged query parameter selects either the current or staged tailored data.

When no Product Tailoring exists for a Product and Store, the Variant Projection is returned without Product Tailoring data.

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.

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
​
id of the VariantProjection.
Query parameters:
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
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
​
CurrencyCode
​
Enables Product price selection and Scoped Price Search.
Pattern: ^[A-Z]{3}0?$​
priceCountry
​
CountryCode
​
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
​
Locale
​
Use for locale-based projection.
The parameter can be passed multiple times.
filter[attributes]
​
String
​
Use for Attribute-based filtering.
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"
    }
  ],
  "categories": [
    {
      "typeId": "category",
      "id": "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a"
    }
  ],
  "categoryOrderHints": {
    "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a": "0.5"
  }
}

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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
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
​
CurrencyCode
​
Enables Product price selection and Scoped Price Search.
Pattern: ^[A-Z]{3}0?$​
priceCountry
​
CountryCode
​
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
​
Locale
​
Use for locale-based projection.
The parameter can be passed multiple times.
filter[attributes]
​
String
​
Use for Attribute-based filtering.
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"
    }
  ],
  "categories": [
    {
      "typeId": "category",
      "id": "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a"
    }
  ],
  "categoryOrderHints": {
    "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a": "0.5"
  }
}

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.

If a ProductTailoring exists for the Product and the given Store, the returned Variant Projection includes the tailored Product name, slug, and description, along with the tailored Variant images, assets, and attributes. The staged query parameter selects either the current or staged tailored data. When no Product Tailoring exists for the Product and Store, the Variant Projection is returned without Product Tailoring data.

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
​
id of the VariantProjection.
Query parameters:
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
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
​
CurrencyCode
​
Enables Product price selection and Scoped Price Search.
Pattern: ^[A-Z]{3}0?$​
priceCountry
​
CountryCode
​
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
​
Locale
​
Use for locale-based projection.
The parameter can be passed multiple times.
filter[attributes]
​
String
​
Use for Attribute-based filtering.
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"
    }
  ],
  "categories": [
    {
      "typeId": "category",
      "id": "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a"
    }
  ],
  "categoryOrderHints": {
    "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a": "0.5"
  }
}

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.

If a ProductTailoring exists for the Product and the given Store, the returned Variant Projection includes the tailored Product name, slug, and description, along with the tailored Variant images, assets, and attributes. The staged query parameter selects either the current or staged tailored data. When no Product Tailoring exists for the Product and Store, the Variant Projection is returned without Product Tailoring data.

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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
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
​
CurrencyCode
​
Enables Product price selection and Scoped Price Search.
Pattern: ^[A-Z]{3}0?$​
priceCountry
​
CountryCode
​
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
​
Locale
​
Use for locale-based projection.
The parameter can be passed multiple times.
filter[attributes]
​
String
​
Use for Attribute-based filtering.
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"
    }
  ],
  "categories": [
    {
      "typeId": "category",
      "id": "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a"
    }
  ],
  "categoryOrderHints": {
    "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a": "0.5"
  }
}

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
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
The parameter can be passed multiple times.
sort
​
String
​

Use to sort query results.

For more information, see Sorting.
The parameter can be passed multiple times.
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
limit
​
Int32
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int32
​
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
​
CurrencyCode
​
Enables Product price selection and Scoped Price Search.
Pattern: ^[A-Z]{3}0?$​
priceCountry
​
CountryCode
​
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
​
Locale
​
Use for locale-based projection.
The parameter can be passed multiple times.
filter[attributes]
​
String
​
Use for Attribute-based filtering.
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
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

VariantProjectionPagedQueryResponse

as
application/json
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"
        }
      ],
      "categories": [
        {
          "typeId": "category",
          "id": "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a"
        }
      ],
      "categoryOrderHints": {
        "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a": "0.5"
      }
    },
    {
      "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"
        }
      ],
      "categories": [
        {
          "typeId": "category",
          "id": "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a"
        }
      ],
      "categoryOrderHints": {
        "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a": "0.9"
      }
    }
  ]
}

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.
If a ProductTailoring exists for a Product and the given Store, the returned Variant Projections include the tailored Product name, slug, and description, along with the tailored Variant images, assets, and attributes. The staged query parameter selects either the current or staged tailored data. When no Product Tailoring exists for a Product and Store, the Variant Projection is returned without Product Tailoring data.

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
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
The parameter can be passed multiple times.
sort
​
String
​

Use to sort query results.

For more information, see Sorting.
The parameter can be passed multiple times.
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
limit
​
Int32
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int32
​
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
​
CurrencyCode
​
Enables Product price selection and Scoped Price Search.
Pattern: ^[A-Z]{3}0?$​
priceCountry
​
CountryCode
​
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
​
Locale
​
Use for locale-based projection.
The parameter can be passed multiple times.
filter[attributes]
​
String
​
Use for Attribute-based filtering.
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
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

VariantProjectionPagedQueryResponse

as
application/json
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"
        }
      ],
      "categories": [
        {
          "typeId": "category",
          "id": "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a"
        }
      ],
      "categoryOrderHints": {
        "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a": "0.5"
      }
    },
    {
      "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"
        }
      ],
      "categories": [
        {
          "typeId": "category",
          "id": "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a"
        }
      ],
      "categoryOrderHints": {
        "5e2f80a1-1b2c-4d3e-8f9a-0b1c2d3e4f5a": "0.9"
      }
    }
  ]
}

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
​
id 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
​
CurrencyCode
​

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

Pattern: ^[A-Z]{3}0?$​
priceCountry
​
CountryCode
​
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
​
Locale
​

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
​
CurrencyCode
​

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

Pattern: ^[A-Z]{3}0?$​
priceCountry
​
CountryCode
​
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
​
Locale
​

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
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
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
​
CurrencyCode
​

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

Pattern: ^[A-Z]{3}0?$​
priceCountry
​
CountryCode
​
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
​
Locale
​

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
​
id 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
​
CurrencyCode
​

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

Pattern: ^[A-Z]{3}0?$​
priceCountry
​
CountryCode
​
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
​
Locale
​

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
​
CurrencyCode
​

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

Pattern: ^[A-Z]{3}0?$​
priceCountry
​
CountryCode
​
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
​
Locale
​

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
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
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
​
CurrencyCode
​

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

Pattern: ^[A-Z]{3}0?$​
priceCountry
​
CountryCode
​
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
​
Locale
​

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}"

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​
Int64​

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​
Int32​
The id of the Variant.
product​
ProductReference​
Reference to the parent Product.
name​
LocalizedString​
Name of the parent Product.
slug​
LocalizedString​
Slug of the parent Product.
description​
LocalizedString​
Description of the parent Product.
categories​
Array of CategoryReference​
Categories assigned to the parent Product.
categoryOrderHints​
CategoryOrderHints​
Order of the parent Product in Categories.
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​
Price​
The selected price based on the price selection query parameters. Only present when price selection parameters are provided.
default​
Boolean​
Whether this Variant is the default Variant of its Product (see Product.defaultVariant).
Default: false​
createdAt​
DateTime​

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

VariantProjectionPagedQueryResponse

limit​
Int64​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
count​
Int64​

Actual number of results returned.

total​
Int64​
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​
Int64​
Number of elements skipped.
Default: 0​Maximum: 10000​
results​
Array of VariantProjection​
VariantProjections matching the query.