Variant Attributes

B2CB2BB2XBETA

Retrieve a lightweight attribute response for variants.

The Variant Attributes endpoint is a read-only sub-resource of Product Projections designed for building attribute selectors on product detail pages (PDPs). It returns only requested Variant-level Attributes and minimal availability data for all Variants of a Product. This makes it suitable for Products with large numbers of Variants.
This endpoint is only available for Projects with productCatalogModel set to Modular.
To use this endpoint, specify which Variant-level Attributes to include in the response using the required filter[attributes] query parameter. Product-level Attributes are ignored.

The response contains:

  • Attribute metadata from the ProductType, including the Attribute name, localized label, and type.
  • Variant entries with only the requested Attributes and lightweight availability data.

Availability

By default, only the no-channel availability (from Inventory Entries without a supply Channel) is included. To include per-channel availability, specify the supply Channel IDs using the filter[supplyChannels] query parameter.

Locale projection

To reduce the response size, use the localeProjection query parameter to filter LocalizedString values to specific locales. This affects both the Attribute metadata labels and the variant Attribute values (for example, lenum labels and ltext values). We recommend using localeProjection to minimize the response size.

Representations

VariantAttributes

A lightweight representation of a Product's Variants with only the requested Attributes and minimal availability data. Designed for building attribute selectors on product detail pages (PDPs).
productId​
String​
Unique identifier of the Product.
productKey​
String​
User-defined unique identifier of the Product.
attributes​
Array of VariantAttributesAttributeMetadata​
Metadata for the requested Attributes, derived from the ProductType. Attributes not found in the ProductType are silently omitted.
variants​
Array of VariantAttributesVariant​

All Variants of the Product with their requested Attributes and availability.

Example: json
{
  "productId": "b5f6e9c0-4a1d-4e8f-b3c7-2d9a8e1f0b4c",
  "productKey": "outdoor-jacket",
  "attributes": [
    {
      "name": "color",
      "label": {
        "en": "Color",
        "de": "Farbe"
      },
      "type": "lenum"
    },
    {
      "name": "size",
      "label": {
        "en": "Size",
        "de": "Groesse"
      },
      "type": "enum"
    }
  ],
  "variants": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sku": "JACKET-RED-M",
      "key": "jacket-red-m",
      "availability": {
        "isOnStock": true,
        "availableQuantity": 10
      },
      "attributes": [
        {
          "name": "color",
          "value": {
            "key": "red",
            "label": {
              "en": "Red",
              "de": "Rot"
            }
          }
        },
        {
          "name": "size",
          "value": {
            "key": "M",
            "label": "M"
          }
        }
      ]
    }
  ]
}

VariantAttributesAttributeMetadata

Metadata about a requested Attribute, derived from the ProductType.
name​
String​
Name of the Attribute as defined in the ProductType.
label​
LocalizedString​
Localized label of the Attribute as defined in the ProductType. Subject to locale projection if localeProjection is specified.
type​
String​
Name of the AttributeType, for example boolean, text, ltext, enum, lenum, number, money, date, time, datetime, reference, set, or nested.

VariantAttributesVariant

A Variant with its requested Attributes and lightweight availability information.

id​
String​
Unique identifier of the Variant.
key​
String​
Key of the Variant.
sku​
String​
SKU of the Variant.
availability​
VariantAttributesAvailability​
Availability information for this variant. Present only if InventoryEntries exist for the variant's SKU.
attributes​
Array of Attribute​
Requested Attributes of the Variant. Only Variant-level Attributes that exist on this Variant and were requested via filter[attributes] are included.

VariantAttributesAvailability

Lightweight availability information for a Variant. Present only if InventoryEntries exist for the Variant's SKU.
isOnStock​
Boolean​

Indicates whether the Variant is in stock.

availableQuantity​
Int​

Number of items of this Variant that are in stock.

channels​
VariantAttributesChannelAvailabilityMap​
Per-channel availability for the requested supply Channels. Present only when the filter[supplyChannels] query parameter is provided.

VariantAttributesChannelAvailability

Availability of a Variant in a specific supply Channel.
isOnStock​
Boolean​
Indicates whether the Variant is in stock in the specified Channel.
availableQuantity​
Int​
Number of items of this Variant that are in stock in the specified Channel.

Get Variant Attributes

Get Variant Attributes by Product ID

GET
https://api.{region}.commercetools.com/{projectKey}/product-projections/{id}/variant-attributes
Returns a lightweight representation of all Variants for a Product, including only the requested variant-level Attributes and minimal availability data.
Designed for building attribute selectors on product detail pages (PDPs) with large numbers of variants. Only available for Projects with productCatalogModel set to Modular.

Product-level Attributes are omitted from the response.

Required access scopes:

  • To retrieve the current representation of published Products (published data), the view_published_products:{projectKey} or view_products:{projectKey} scope is required.
  • To retrieve the staged representation of Products (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.
id
​
String
​
id of the ProductProjection.
Query parameters:
staged
​
Boolean
​
To retrieve the staged Product Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false​
localeProjection
​
Locale
​
Use for locale-based projection.
The parameter can be passed multiple times.
filter[attributes]
​
String
​
Variant-level Attribute names to include in the response. Must be provided at least once. Repeat for multiple Attributes, for example filter[attributes]=color&filter[attributes]=size.
Only variant-level Attributes are returned. Product-level Attributes are silently omitted. Attributes not found in the ProductType are silently omitted.
The parameter can be passed multiple times.
filter[supplyChannels]
​
String
​
Supply Channel IDs to include in the availability data. If omitted, only the no-channel availability is returned. If provided, per-channel availability is added alongside the no-channel availability.
The parameter can be passed multiple times.
Response:
200

VariantAttributes

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/{id}/variant-attributes?filter[attributes]={filter[attributes]} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: VariantAttributesjson
{
  "productId": "b5f6e9c0-4a1d-4e8f-b3c7-2d9a8e1f0b4c",
  "productKey": "outdoor-jacket",
  "attributes": [
    {
      "name": "color",
      "label": {
        "en": "Color",
        "de": "Farbe"
      },
      "type": "lenum"
    },
    {
      "name": "size",
      "label": {
        "en": "Size",
        "de": "Groesse"
      },
      "type": "enum"
    }
  ],
  "variants": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sku": "JACKET-RED-M",
      "key": "jacket-red-m",
      "availability": {
        "isOnStock": true,
        "availableQuantity": 10
      },
      "attributes": [
        {
          "name": "color",
          "value": {
            "key": "red",
            "label": {
              "en": "Red",
              "de": "Rot"
            }
          }
        },
        {
          "name": "size",
          "value": {
            "key": "M",
            "label": "M"
          }
        }
      ]
    }
  ]
}

Get Variant Attributes by Product Key

GET
https://api.{region}.commercetools.com/{projectKey}/product-projections/key={key}/variant-attributes
Returns a lightweight representation of all Variants for a Product, including only the requested variant-level Attributes and minimal availability data.
Designed for building attribute selectors on product detail pages (PDPs) with large numbers of variants. Only available for Projects with productCatalogModel set to Modular.

Product-level Attributes are omitted from the response.

Required access scopes:

  • To retrieve the current representation of published Products (published data), the view_published_products:{projectKey} or view_products:{projectKey} scope is required.
  • To retrieve the staged representation of Products (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.
key
​
String
​
key of the ProductProjection.
Query parameters:
staged
​
Boolean
​
To retrieve the staged Product Projection (only for API Clients that have the view_products:{projectKey} scope), set to true.
Default: false​
localeProjection
​
Locale
​
Use for locale-based projection.
The parameter can be passed multiple times.
filter[attributes]
​
String
​
Variant-level Attribute names to include in the response. Must be provided at least once. Repeat for multiple Attributes, for example filter[attributes]=color&filter[attributes]=size.
Only variant-level Attributes are returned. Product-level Attributes are silently omitted. Attributes not found in the ProductType are silently omitted.
The parameter can be passed multiple times.
filter[supplyChannels]
​
String
​
Supply Channel IDs to include in the availability data. If omitted, only the no-channel availability is returned. If provided, per-channel availability is added alongside the no-channel availability.
The parameter can be passed multiple times.
Response:
200

VariantAttributes

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/key={key}/variant-attributes?filter[attributes]={filter[attributes]} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: VariantAttributesjson
{
  "productId": "b5f6e9c0-4a1d-4e8f-b3c7-2d9a8e1f0b4c",
  "productKey": "outdoor-jacket",
  "attributes": [
    {
      "name": "color",
      "label": {
        "en": "Color",
        "de": "Farbe"
      },
      "type": "lenum"
    },
    {
      "name": "size",
      "label": {
        "en": "Size",
        "de": "Groesse"
      },
      "type": "enum"
    }
  ],
  "variants": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sku": "JACKET-RED-M",
      "key": "jacket-red-m",
      "availability": {
        "isOnStock": true,
        "availableQuantity": 10
      },
      "attributes": [
        {
          "name": "color",
          "value": {
            "key": "red",
            "label": {
              "en": "Red",
              "de": "Rot"
            }
          }
        },
        {
          "name": "size",
          "value": {
            "key": "M",
            "label": "M"
          }
        }
      ]
    }
  ]
}

Get Variant Attributes in Store

Get Variant Attributes in Store by Product ID

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/{id}/variant-attributes
Returns a lightweight representation of all Variants for a Product, including only the requested variant-level Attributes and minimal availability data, scoped to a specific Store.
Designed for building attribute selectors on product detail pages (PDPs) with large numbers of variants. Only available for Projects with productCatalogModel set to Modular.

Product-level Attributes are omitted from the response.

Required access scopes:

  • To retrieve the current representation of published Products (published data), the view_published_products:{projectKey} and view_products:{projectKey}:{storeKey} scope is required.
  • To retrieve the staged representation of Products (draft data), the API Client must have the view_products:{projectKey} and view_products:{projectKey}:{storeKey} scope.
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 ProductProjection.
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​
localeProjection
​
Locale
​
Use for locale-based projection.
The parameter can be passed multiple times.
filter[attributes]
​
String
​
Variant-level Attribute names to include in the response. Must be provided at least once. Repeat for multiple Attributes, for example filter[attributes]=color&filter[attributes]=size.
Only variant-level Attributes are returned. Product-level Attributes are silently omitted. Attributes not found in the ProductType are silently omitted.
The parameter can be passed multiple times.
filter[supplyChannels]
​
String
​
Supply Channel IDs to include in the availability data. If omitted, only the no-channel availability is returned. If provided, per-channel availability is added alongside the no-channel availability.
The parameter can be passed multiple times.
Response:
200

VariantAttributes

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/{id}/variant-attributes?filter[attributes]={filter[attributes]} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: VariantAttributesjson
{
  "productId": "b5f6e9c0-4a1d-4e8f-b3c7-2d9a8e1f0b4c",
  "productKey": "outdoor-jacket",
  "attributes": [
    {
      "name": "color",
      "label": {
        "en": "Color",
        "de": "Farbe"
      },
      "type": "lenum"
    },
    {
      "name": "size",
      "label": {
        "en": "Size",
        "de": "Groesse"
      },
      "type": "enum"
    }
  ],
  "variants": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sku": "JACKET-RED-M",
      "key": "jacket-red-m",
      "availability": {
        "isOnStock": true,
        "availableQuantity": 10
      },
      "attributes": [
        {
          "name": "color",
          "value": {
            "key": "red",
            "label": {
              "en": "Red",
              "de": "Rot"
            }
          }
        },
        {
          "name": "size",
          "value": {
            "key": "M",
            "label": "M"
          }
        }
      ]
    }
  ]
}

Get Variant Attributes in Store by Product Key

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/key={key}/variant-attributes
Returns a lightweight representation of all Variants for a Product, including only the requested variant-level Attributes and minimal availability data, scoped to a specific Store.
Designed for building attribute selectors on product detail pages (PDPs) with large numbers of variants. Only available for Projects with productCatalogModel set to Modular.

Product-level Attributes are omitted from the response.

Required access scopes:

  • To retrieve the current representation of published Products (published data), the view_published_products:{projectKey} and view_products:{projectKey}:{storeKey} scope is required.
  • To retrieve the staged representation of Products (draft data), the API Client must have the view_products:{projectKey} and view_products:{projectKey}:{storeKey} scope.
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 ProductProjection.
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​
localeProjection
​
Locale
​
Use for locale-based projection.
The parameter can be passed multiple times.
filter[attributes]
​
String
​
Variant-level Attribute names to include in the response. Must be provided at least once. Repeat for multiple Attributes, for example filter[attributes]=color&filter[attributes]=size.
Only variant-level Attributes are returned. Product-level Attributes are silently omitted. Attributes not found in the ProductType are silently omitted.
The parameter can be passed multiple times.
filter[supplyChannels]
​
String
​
Supply Channel IDs to include in the availability data. If omitted, only the no-channel availability is returned. If provided, per-channel availability is added alongside the no-channel availability.
The parameter can be passed multiple times.
Response:
200

VariantAttributes

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/key={key}/variant-attributes?filter[attributes]={filter[attributes]} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: VariantAttributesjson
{
  "productId": "b5f6e9c0-4a1d-4e8f-b3c7-2d9a8e1f0b4c",
  "productKey": "outdoor-jacket",
  "attributes": [
    {
      "name": "color",
      "label": {
        "en": "Color",
        "de": "Farbe"
      },
      "type": "lenum"
    },
    {
      "name": "size",
      "label": {
        "en": "Size",
        "de": "Groesse"
      },
      "type": "enum"
    }
  ],
  "variants": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sku": "JACKET-RED-M",
      "key": "jacket-red-m",
      "availability": {
        "isOnStock": true,
        "availableQuantity": 10
      },
      "attributes": [
        {
          "name": "color",
          "value": {
            "key": "red",
            "label": {
              "en": "Red",
              "de": "Rot"
            }
          }
        },
        {
          "name": "size",
          "value": {
            "key": "M",
            "label": "M"
          }
        }
      ]
    }
  ]
}