# 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](/api/projects/productProjections.md#current--staged), 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](/api/projects/productProjections.md#prices) 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](/api/projects/product-tailoring.md). 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.

## Representations

### VariantProjection

[type definition](/api/projects/variant-projections.md?urn=ctp:api:type:VariantProjection).

### VariantProjectionPagedQueryResponse

[type definition](/api/projects/variant-projections.md?urn=ctp:api:type:VariantProjectionPagedQueryResponse).

## Get VariantProjection

### Get VariantProjection by ID

[endpoint definition](/api/projects/variant-projections.md?urn=ctp:api:endpoint:/\{projectKey}/variant-projections/\{id}:GET).

### Get VariantProjection by Key

[endpoint definition](/api/projects/variant-projections.md?urn=ctp:api:endpoint:/\{projectKey}/variant-projections/key=\{key}:GET).

## Get VariantProjection in Store

### Get VariantProjection in Store by ID

[endpoint definition](/api/projects/variant-projections.md?urn=ctp:api:endpoint:/\{projectKey}/in-store/key=\{storeKey}/variant-projections/\{id}:GET).

### Get VariantProjection in Store by Key

[endpoint definition](/api/projects/variant-projections.md?urn=ctp:api:endpoint:/\{projectKey}/in-store/key=\{storeKey}/variant-projections/key=\{key}:GET).

## Query VariantProjections

[endpoint definition](/api/projects/variant-projections.md?urn=ctp:api:endpoint:/\{projectKey}/variant-projections:GET).

## Query VariantProjections in Store

[endpoint definition](/api/projects/variant-projections.md?urn=ctp:api:endpoint:/\{projectKey}/in-store/key=\{storeKey}/variant-projections:GET).

## Check if VariantProjection exists

### Check if VariantProjection exists by ID

[endpoint definition](/api/projects/variant-projections.md?urn=ctp:api:endpoint:/\{projectKey}/variant-projections/\{id}:HEAD).

### Check if VariantProjection exists by Key

[endpoint definition](/api/projects/variant-projections.md?urn=ctp:api:endpoint:/\{projectKey}/variant-projections/key=\{key}:HEAD).

### Check if VariantProjection exists by Query Predicate

[endpoint definition](/api/projects/variant-projections.md?urn=ctp:api:endpoint:/\{projectKey}/variant-projections:HEAD).

## Check if VariantProjection exists in Store

### Check if VariantProjection exists in Store by ID

[endpoint definition](/api/projects/variant-projections.md?urn=ctp:api:endpoint:/\{projectKey}/in-store/key=\{storeKey}/variant-projections/\{id}:HEAD).

### Check if VariantProjection exists in Store by Key

[endpoint definition](/api/projects/variant-projections.md?urn=ctp:api:endpoint:/\{projectKey}/in-store/key=\{storeKey}/variant-projections/key=\{key}:HEAD).

### Check if VariantProjection exists in Store by Query Predicate

[endpoint definition](/api/projects/variant-projections.md?urn=ctp:api:endpoint:/\{projectKey}/in-store/key=\{storeKey}/variant-projections:HEAD).

## Related pages

- [Area overview page with navigation](/api.md)
- [Previous page: Variant Attributes](/api/projects/variant-attributes.md)