Product Projections

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

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 shop (storefront) will get the product data by querying or searching the current product projections.
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.

Representations

ProductProjection

Get ProductProjection

Get ProductProjection by ID

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

Endpoint: /{projectKey}/product-projections/{id}
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: ProductProjection
Query Parameters:

  • staged - Boolean - Optional (Defaults to false)
    Whether to query for the current or staged projections.
  • 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.

Get ProductProjection by Key

Gets the current or staged representation of a product found by Key.

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

  • staged - Boolean - Optional (Defaults to false)
    Whether to query for the current or staged projections.
  • 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.

Query ProductProjections

You can use the product projections query endpoint to get the current or staged representations of Products. REMARK: We suggest to use 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
OAuth2 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with the results array of ProductProjection
Query Parameters:

  • where - Predicate - Optional
  • sort - Sort - Optional Sorting is only possible for not in arrays nested data e.g. 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.
  • 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.

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