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 EmbeddedPrices 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 EmbeddedPrices also affects line items of carts bound to a store.

Projecting prices only works with EmbeddedPrices, there is currently no support for StandalonePrices.

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.

Product Selection assignments

To retrieve only those Product Projections that are assigned to a particular Product Selection use the Get ProductProjection in a Store endpoints. For Product Selections in which only particular Product Variants are assigned to, these endpoints return only those Variants in the retrieved Product Projections.

Representations

ProductProjection

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:

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:

Get ProductProjection by Key

Gets the current or staged representation of a product found by Product 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:

Get ProductProjection in a Store by Key BETA

Gets the current or staged representation of a product found by Product 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:

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.

Querying on Product Attributes is discouraged as inefficient pattern. We recommend using the performance-optimized Search Product Projections endpoint instead whenever your use-case allows it.

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:

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