Product Projections

A Product Projection is a representation of Product data restricted to either its current or staged data. Additionally, you can further limit the data to given Locales, specific Prices, the Product's availability on inventory supply channels, or its assignment to specific Product Selections. This allows you to tailor the query response to your use case.

The query endpoint provides Query Predicates. The search endpoint should be the preferred option for Product search as it provides full-text search, filtering, faceting, and better response times.

To optimize the usage of this endpoint for your project, check our performance tips.

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 Product 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 Product Projection.

Prices

To remove unneeded Embedded 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 Product Projection:

Prices with a distribution Channel that is included in the Store's distributionChannels
Prices without a distribution Channel

Likewise, if the store has countries set, then only the following prices are included in the projection:

prices with a country that is included in the store's countries
prices without country

Projecting on Embedded Prices also affects Line Items of carts bound to a store.

Projecting prices only works with Embedded Prices, 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 entries without a 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 Store endpoints. For Product Selections that only have particular Product Variants assigned, these endpoints return only those Variants in the retrieved Product Projections.

Representations

ProductProjection

ProductProjectionPagedQueryResponse

ProductProjection

`id` String	Unique identifier of the Product.
`version` Int	Current version of the Product.
`key` String	User-defined unique identifier of the Product.
`productType` ProductTypeReference	The ProductType defining the Attributes of the Product.
`name` LocalizedString	Name of the Product.
`description` LocalizedString	Description of the Product.
`slug` LocalizedString	User-defined identifier used in a deep-link URL for the Product. Must be unique across a Project, but can be the same for Products in different locales. Matches the pattern `[a-zA-Z0-9_-]{2,256}`. For good performance, indexes are provided for the first 15 `languages` set in the Project.
`categories` Array of CategoryReference	Categories assigned to the Product.
`categoryOrderHints` CategoryOrderHints	Order of Product in Categories.
`metaTitle` LocalizedString	Title of the Product displayed in search results.
`metaDescription` LocalizedString	Description of the Product displayed in search results below the meta title.
`metaKeywords` LocalizedString	Keywords that give additional information about the Product to search engines.
`searchKeywords` SearchKeywords	Used by Product Suggestions, but is also considered for a full text search.
`hasStagedChanges` Boolean	`true` if the staged data is different from the current data.
`published` Boolean	`true` if the Product is published.
`masterVariant` ProductVariant	The Master Variant of the Product.
`variants` Array of ProductVariant	Additional Product Variants.
`taxCategory` TaxCategoryReference	The TaxCategory of the Product.
`state` StateReference	State of the Product.
`reviewRatingStatistics` ReviewRatingStatistics	Review statistics of the Product.
`priceMode` ProductPriceModeEnum	Indicates whether the Prices of the Product Projection are embedded or standalone. Projecting Prices only works with `Embedded`, there is currently no support for `Standalone`.
`createdAt` DateTime	Date and time (UTC) the ProductProjection was initially created.
`lastModifiedAt` DateTime	Date and time (UTC) the ProductProjection was last updated.

ProductProjectionPagedQueryResponse

`limit` Int	Number of results requested.
`count` Int	Actual number of results returned.
`total` Int	Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter `withTotal=false`. When the results are filtered with a Query Predicate, `total` is subject to a limit.
`offset` Int	Number of elements skipped.
`results` Array of ProductProjection	ProductProjections matching the query.

Get ProductProjection

Get ProductProjection by ID

GET

https://api.{region}.commercetools.com/{projectKey}/product-projections/{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.

OAuth 2.0 Scopes:

view_products:{projectKey}view_published_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the ProductProjection.

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`staged` Boolean	To retrieve the staged Product Projection (only for API Clients that have the `view_products:{projectKey}` scope), set to `true`. Default: `false`
`priceCurrency` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`localeProjection` Locale	Use for locale-based projection. The parameter can be passed multiple times.
`storeProjection` String	`key` of an existing Store. If the Store has defined some languages, countries, distribution or supply Channels, they are used for projections based on locale, price, and inventory. If the Store has defined Product Selections, they have no effect on the results of this query.

Response:

200ProductProjectionasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: ProductProjectionjson

{
  "id": "080feded-4f74-4d31-9309-f7ef6b7f1279",
  "version": 3,
  "productType": {
    "typeId": "product-type",
    "id": "1c095f1b-e638-4c7e-86c4-c58df873fca6"
  },
  "name": {
    "en": "Some Products"
  },
  "categories": [],
  "slug": {
    "en": "product_slug_jxeutnxwkswk"
  },
  "masterVariant": {
    "id": 1,
    "prices": [],
    "images": [],
    "attributes": [
      {
        "name": "text1",
        "value": {
          "it": "italian1",
          "de": "german1",
          "en": "englisch1"
        }
      }
    ]
  },
  "variants": [],
  "searchKeywords": {},
  "hasStagedChanges": false,
  "published": true,
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "2014-01-07T15:25:50.034Z"
}

Get ProductProjection by Key

GET

https://api.{region}.commercetools.com/{projectKey}/product-projections/key={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.

OAuth 2.0 Scopes:

view_products:{projectKey}view_published_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the ProductProjection.

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`staged` Boolean	To retrieve the staged Product Projection (only for API Clients that have the `view_products:{projectKey}` scope), set to `true`. Default: `false`
`priceCurrency` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`localeProjection` Locale	Use for locale-based projection. The parameter can be passed multiple times.
`storeProjection` String	`key` of an existing Store. If the Store has defined some languages, countries, distribution or supply Channels, they are used for projections based on locale, price, and inventory. If the Store has defined Product Selections, they have no effect on the results of this query.

Response:

200ProductProjectionasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: ProductProjectionjson

{
  "id": "080feded-4f74-4d31-9309-f7ef6b7f1279",
  "version": 3,
  "productType": {
    "typeId": "product-type",
    "id": "1c095f1b-e638-4c7e-86c4-c58df873fca6"
  },
  "name": {
    "en": "Some Products"
  },
  "categories": [],
  "slug": {
    "en": "product_slug_jxeutnxwkswk"
  },
  "masterVariant": {
    "id": 1,
    "prices": [],
    "images": [],
    "attributes": [
      {
        "name": "text1",
        "value": {
          "it": "italian1",
          "de": "german1",
          "en": "englisch1"
        }
      }
    ]
  },
  "variants": [],
  "searchKeywords": {},
  "hasStagedChanges": false,
  "published": true,
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "2014-01-07T15:25:50.034Z"
}

Get ProductProjection in Store

Get ProductProjection in Store by ID

GET

https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/{id}

Gets the current or staged representation of a Product by its ID in the specified Store. If the Store has defined some languages, countries, distribution, supply Channels, and/or Product Selection, they are used for projections based on locale, price, and inventory.

If ProductSelection is used, it affects the availability of the Product in the specified Store.

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

OAuth 2.0 Scopes:

view_products:{projectKey}view_published_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`storeKey` String	`key` of the Store.
`id` String	`id` of the ProductProjection.

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`staged` Boolean	To retrieve the staged Product Projection (only for API Clients that have the `view_products:{projectKey}` scope), set to `true`. Default: `false`
`priceCurrency` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`localeProjection` Locale	Use for locale-based projection. The parameter can be passed multiple times.

Response:

200ProductProjectionasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Get ProductProjection in Store by Key

GET

https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/key={key}

Gets the current or staged representation of a Product by its key in the specified Store. If the Store has defined some languages, countries, distribution, supply Channels, and/or Product Selection, they are used for projections based on locale, price, and inventory.

If ProductSelection is used, it affects the availability of the Product in the specified Store.

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

OAuth 2.0 Scopes:

view_products:{projectKey}view_published_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`storeKey` String	`key` of the Store.
`key` String	`key` of the ProductProjection.

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`staged` Boolean	To retrieve the staged Product Projection (only for API Clients that have the `view_products:{projectKey}` scope), set to `true`. Default: `false`
`priceCurrency` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`localeProjection` Locale	Use for locale-based projection. The parameter can be passed multiple times.

Response:

200ProductProjectionasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Query ProductProjections

Querying on Product Attributes should not be used in high-volume use cases as it is an inefficient pattern.

We recommend using the performance-optimized Product Projection Search endpoint instead whenever your use case allows it.

GET

https://api.{region}.commercetools.com/{projectKey}/product-projections

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.

OAuth 2.0 Scopes:

view_products:{projectKey}view_published_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

`where` QueryPredicate	The parameter can be passed multiple times.
`/^var[.][a-zA-Z0-9]+$/` Any string parameter matching this regular expression	Predicate parameter values. The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested.
`offset` Int	Number of elements skipped.
`withTotal` Boolean	Controls the calculation of the total number of query results. Set to `false` to improve query performance when the `total` is not needed. Default: `true`
`staged` Boolean	To retrieve the staged Product Projection (only for API Clients that have the `view_products:{projectKey}` scope), set to `true`. Default: `false`
`priceCurrency` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`localeProjection` Locale	Use for locale-based projection. The parameter can be passed multiple times.
`storeProjection` String	`key` of an existing Store. If the Store has defined some languages, countries, distribution or supply Channels, they are used for projections based on locale, price, and inventory. If the Store has defined Product Selections, they have no effect on the results of this query.

Response:

200ProductProjectionPagedQueryResponseasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: ProductProjectionPagedQueryResponsejson

{
  "limit": 20,
  "offset": 0,
  "count": 2,
  "total": 2,
  "results": [
    {
      "id": "080feded-4f74-4d31-9309-f7ef6b7f1279",
      "version": 3,
      "productType": {
        "typeId": "product-type",
        "id": "1c095f1b-e638-4c7e-86c4-c58df873fca6"
      },
      "name": {
        "en": "Some Products"
      },
      "categories": [],
      "slug": {
        "en": "product_slug_jxeutnxwkswk"
      },
      "masterVariant": {
        "id": 1,
        "prices": [],
        "images": [],
        "attributes": [
          {
            "name": "text1",
            "value": {
              "it": "italian1",
              "de": "german1",
              "en": "englisch1"
            }
          }
        ]
      },
      "variants": [],
      "searchKeywords": {},
      "hasStagedChanges": false,
      "published": true,
      "createdAt": "1970-01-01T00:00:00.001Z",
      "lastModifiedAt": "2014-01-07T15:25:50.034Z"
    },
    {
      "id": "e779ec1a-0a98-4135-8344-d51bdafd4fe6",
      "version": 6,
      "productType": {
        "typeId": "product-type",
        "id": "bac5ef74-e0f9-4792-8439-ab84b270599e"
      },
      "name": {
        "en": "product with dates"
      },
      "description": {
        "en": "<p>Used to test the various date attributes<br></p>"
      },
      "categories": [],
      "slug": {
        "aa": "product-with-dates-1432797256269",
        "de": "product-with-dates-1432797256269",
        "en": "product-with-dates-1432797256269"
      },
      "masterVariant": {
        "id": 1,
        "prices": [],
        "images": [],
        "attributes": [
          {
            "name": "aboolean",
            "value": true
          }
        ]
      },
      "variants": [],
      "searchKeywords": {},
      "hasStagedChanges": true,
      "published": true,
      "createdAt": "2015-05-28T07:15:48.738Z",
      "lastModifiedAt": "2015-05-28T07:19:38.624Z"
    }
  ]
}

Check if ProductProjection exists

Check if ProductProjection exists by ID

HEAD

https://api.{region}.commercetools.com/{projectKey}/product-projections/{id}

Checks if the current or staged representation of a Product exists for a given id. Returns a 200 OK status if the ProductProjection exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:

view_products:{projectKey}view_published_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the ProductProjection.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/product-projections/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if ProductProjection exists by Key

HEAD

https://api.{region}.commercetools.com/{projectKey}/product-projections/key={key}

Checks if the current or staged representation of a Product exists for a given key. Returns a 200 OK status if the ProductProjection exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:

view_products:{projectKey}view_published_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the ProductProjection.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/product-projections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if ProductProjection exists by Query Predicate

HEAD

https://api.{region}.commercetools.com/{projectKey}/product-projections

Checks if the current or staged representation of a Product exists for a given Query Predicate. Returns a 200 OK status if any ProductProjections match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:

view_products:{projectKey}view_published_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

where

QueryPredicate

The parameter can be passed multiple times.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/product-projections -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if ProductProjection exists in Store

Check if ProductProjection exists in Store by ID

HEAD

https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/{id}

Checks if the current or staged representations of a Product exists for a given id in the specified Store. Returns a 200 OK status if the ProductProjection exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:

view_products:{projectKey}view_published_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`storeKey` String	`key` of the Store.
`id` String	`id` of the ProductProjection.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if ProductProjection exists in Store by Key

HEAD

https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/key={key}

Checks if the current or staged representations of a Product exists for a given key in the specified Store. Returns a 200 OK status if the ProductProjection exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:

view_products:{projectKey}view_published_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`storeKey` String	`key` of the Store.
`key` String	`key` of the ProductProjection.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"