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 BETA

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 BETA

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 BETA

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

Get ProductProjection

Get ProductProjection by ID

Gets the current or staged representation of a product in a catalog by 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 BETA
    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 BETA
    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 BETA
    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 BETA
    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 the results 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 BETA
    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 BETA
    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