Product Projections

Product projection is a projected representation of a product that shows the product with its current or staged data.

The query endpoint provides the query predicates. The search endpoint provides full-text search, filtering, and faceting functionality, offers better response times and should therefore be the preferred option.

Projection dimensions

Current / staged

At any time, a Product has either one or two projected representations, depending on whether the product is currently published. Only published products have a current projected representation. Newly created products only have a staged projected representation. In general, a storefront application will get the product data by querying or searching the current product projections.

Locales

To remove unneeded translations from product projections, LocalizedStrings can be filtered based on locales. The locales that should be included in the projection are determined in the following order:

locales defined directly with the query parameter localeProjection.
locales configured in the Store that is specified with the query parameter storeProjection.

Projecting on locales also affects line items of carts bound to a store.

If no translation is found on a given field for the specified locales, another locale is used as fallback. This ensures that required fields cannot remain empty in the projection.

Prices

To remove unneeded Prices from product projections, they can be filtered based on the product distribution channels configured in the Store that is specified with the query parameter storeProjection.

If the store has distributionChannels set, then only the following prices are included in the projection:

prices with a distribution channel that is included in the store's distributionChannels
prices without distribution channel

Projecting on prices also affects line items of carts bound to a store.

Inventory entries

To remove unneeded Product Variant Availabilities from product projections, they can be filtered based on the inventory supply channels configured in the Store that is specified with the query parameter storeProjection.

If the store has supplyChannels set, then only the following inventory entries are included in the projected product variants availability:

inventory entries with a supply channel that is included in the store's supplyChannels
inventory entry without supply channel

Projecting on inventory entries also affects line items of carts bound to a store.

Representations

ProductProjection

id - String
The unique ID of the Product.
key - String - Optional
User-specific unique identifier of the Product.
version - Number
The current version of the Product.
createdAt - DateTime
lastModifiedAt - DateTime
productType - Reference to a ProductType
name - LocalizedString
description - LocalizedString - Optional
slug - LocalizedString
categories - Array of Reference to a Category
References to categories the product is in.
categoryOrderHints - CategoryOrderHints - Optional
metaTitle - LocalizedString - Optional
metaDescription - LocalizedString - Optional
metaKeywords - LocalizedString - Optional
searchKeywords - SearchKeywords
hasStagedChanges - Boolean
published - Boolean
masterVariant - ProductVariant
variants - Array of ProductVariant
taxCategory - Reference to a TaxCategory - Optional
state - Reference to a State - Optional
reviewRatingStatistics - ReviewRatingStatistics - Optional
Statistics about the review ratings taken into account for this product.

Get ProductProjection

Get ProductProjection by ID

Gets the current or staged representation of a product by its ID.

When used with an API Client that has the view_published_products:{projectKey} scope, this endpoint only returns published (current) Product Projections.

Endpoint: /{projectKey}/product-projections/{id}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}, view_published_products:{projectKey}
Response Representation: ProductProjection
Query Parameters:

staged - Boolean - Optional (Defaults to false)
Whether to query for the current or staged projections. Must be false when using API clients that have the view_published_products:{projectKey} scope.
priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
storeProjection - String - Optional
Key of an existing Store.
If the Store defines some languages, distribution channels or supply channels, they are used to enable locale based projection, price based projection and inventory based projection respectively.
localeProjection - String - Optional
IETF language tag.
Enables locale based projection.
To set more than one locale, use this query parameter multiple times.

Get ProductProjection in a Store by ID BETA

Gets the current or staged representation of a product by its ID from a specific Store. The {storeKey} path parameter maps to a Store's key.

If the Store defines some languages, distribution channels or supply channels, they are used to enable locale based projection, price based projection and inventory based projection respectively.

When used with an API Client that has the view_published_products:{projectKey} scope, this endpoint only returns published (current) Product Projections.

Endpoint: /{projectKey}/in-store/key={storeKey}/product-projections/{id}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}, view_published_products:{projectKey}
Response Representation: ProductProjection
Query Parameters:

staged - Boolean - Optional (defaults to false)
Whether to query for the current or staged projections. Must be false when using API Clients that have the view_published_products:{projectKey} scope.
priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
localeProjection - String - Optional
IETF language tag.
Enables locale based projection.
To set more than one locale, use this query parameter multiple times.

Get ProductProjection by Key

Gets the current or staged representation of a product found by Key. When used with an API client that has the view_published_products:{projectKey} scope, this endpoint only returns published (current) product projections.

Endpoint: /{projectKey}/product-projections/key={key}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}, view_published_products:{projectKey}
Response Representation: ProductProjection
Query Parameters:

staged - Boolean - Optional (Defaults to false)
Whether to query for the current or staged projections.
Must be false when using API clients that have the view_published_products:{projectKey} scope.
priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
storeProjection - String - Optional
Key of an existing Store.
If the Store defines some languages, distribution channels or supply channels, they are used to enable locale based projection, price based projection and inventory based projection respectively.
localeProjection - String - Optional
IETF language tag.
Enables locale based projection.
To set more than one locale, use this query parameter multiple times.

Get ProductProjection in a Store by Key BETA

Gets the current or staged representation of a product found by Key from a specific Store. The {storeKey} path parameter maps to a Store's key.

If the Store defines some languages, distribution channels or supply channels, they are used to enable locale based projection, price based projection and inventory based projection respectively.

When used with an API Client that has the view_published_products:{projectKey} scope, this endpoint only returns published (current) Product Projections.

Endpoint: /{projectKey}/in-store/key={storeKey}/product-projections/key={key}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}, view_published_products:{projectKey}
Response Representation: ProductProjection
Query Parameters:

staged - Boolean - Optional (defaults to false)
Whether to query for the current or staged projections.
Must be false when using API Clients that have the view_published_products:{projectKey} scope.
priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
localeProjection - String - Optional
IETF language tag.
Enables locale based projection.
To set more than one locale, use this query parameter multiple times.

Query ProductProjections

You can use the product projections query endpoint to get the current or staged representations of Products. When used with an API client that has the view_published_products:{projectKey} scope, this endpoint only returns published (current) product projections.

We suggest using the performance optimized search endpoint which has a bunch functionalities, the query API lacks, like sorting on custom attributes, etc.

Endpoint: /{projectKey}/product-projections
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}, view_published_products:{projectKey}
Response Representation: PagedQueryResult with results containing an array of ProductProjection
Query Parameters:

where - Query Predicate - Optional
sort - Sort - Optional Sorting is only possible for not in arrays nested data for example sku of masterVariant, createdAt, lastModifiedAt, name.en, etc. Sorting for prices or custom attributes via Query API is not possible.
limit - Number - Optional
offset - Number - Optional
staged - Boolean - Optional (Defaults to false)
Whether to query for the current or staged projections.
Must be false when using API clients that have the view_published_products:{projectKey} scope.
priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
storeProjection - String - Optional
Key of an existing Store.
If the Store defines some languages, distribution channels or supply channels, they are used to enable locale based projection, price based projection and inventory based projection respectively.
localeProjection - String - Optional
IETF language tag.
Enables locale based projection.
To set more than one locale, use this query parameter multiple times.

Example:
GET /{projectKey}/product-projections?staged=true&limit=10