Product Projections

Retrieve product data projected to the context of your Store, specific to the customer locale and country.

The intended use of the Product Projections API is to provide product data for product detail pages (PDPs) and product listing pages (PLPs) in your storefront applications. Product Projections represent the state of a Product as visible to customers, taking into account the Product's publication status, the Store context, and various projection dimensions.

When retrieving Product Projections, you can specify whether the data should be restricted to either its current or staged data.
To tailor the query response to your use case, you can further filter the data based on context such as:

given Locales,
specific Prices,
the Product's availability on inventory supply channels, or
its assignment to specific Product Selections.

Use the Query ProductProjections endpoint of this API for queries on non-localized standard fields, such as id and key.

For queries on Attributes and localized fields, use the Product Search API instead that is the preferred option for product discovery. It provides full-text search, filtering, faceting, and lower response times compared to the Query ProductProjections endpoint, see performance tips.

This API provides read-only access to Product Projections. For managing Products, use the Products API instead.

When the Project has the ProductCatalogModel set to Modular, masterVariant and variants in the ProductProjection object are empty. Use the Variant Projections API to retrieve variant data instead.

Learn more about how to implement a product detail page (PDP) using Product Projections in our self-paced Build product detail pages module.

Projection dimensions

Current / staged

Every Product resource contains two representations of its data, from the moment it is created:

staged: Represents the draft data. This is where all pending changes, such as edits to descriptions, prices, variants, are held before they are made public.
current: Represents the live version of the product data visible to customers in a storefront.

The platform detects updates made to the staged representation. If there are differences compared to current, the hasStagedChanges flag in the ProductCatalogData is set to true.

Publishing

If your product data is ready for your customers, you can publish the Product.

During this process, the platform:

Copies the staged data to current.
Sets the published flag to true in the ProductCatalogData.
Sets the hasStagedChanges flag to false in the ProductCatalogData.

Typical storefront applications retrieve product data by querying or searching only the current representation of published Products. You can restrict access to only published Products by assigning the view_published_products:{projectKey} scope instead of view_products:{projectKey}.

Unpublishing

Unpublishing a Product makes it inaccessible through the Product Projection endpoints by default and removes it from the Product Search index. Unpublishing only sets the published flag to false in the ProductCatalogData; it does not alter the data stored in the current or staged representations.

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, the API checks the Project languages in their configured order and uses the first localized value it finds. This ensures that required fields cannot remain empty in the Product Projection.

Prices

Price projection is a mechanism for filtering the prices included in a Product Projection. It ensures that the API response for a product contains only the prices relevant to a specific context, such as a particular country, customer group or distribution channel. This practice simplifies client-side logic by preventing API responses from being cluttered with a product's entire, often extensive, price list.

Projection by Store

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 the Product Projection will only include the Prices meeting one of the following criteria:

The Price has a distribution Channel that is included in the Store's distributionChannels.
The Price does not have a distribution Channel assigned.

Likewise, if the Store has countries set, then the projection will only include the Prices that meet one of the following criteria:

The Price has a country that is included in the Store's countries.
The Price does not have any country assigned.

This filtering logic applies to the prices array within the Product Projection.

For price projection by Store to apply, the Product priceMode must be Embedded.

Standalone Prices are not computed using Store channels or countries. To retrieve a Standalone Price in Product Projections, apply projection by price selection.

Projection by price selection

Price selection allows you to select one price for your Product that is the best matching price for the customer. This best match can be either an Embedded Price of the Product Variant or a Standalone Price associated with the Product Variant. The platform selects the best matching price based on the price selection parameters, such as priceCurrency, priceCountry, priceCustomerGroup, and priceChannel.

When price selection is applied, the Product Variants that are returned will contain two fields with Prices:

The prices array contains Embedded Prices (optionally projected by Store); Standalone Prices are never included.
The optional price field contains the best matching price based on the provided price selection parameters. This can be either an Embedded Price or a Standalone Price.

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.

Attributes

To reduce the response size and improve performance, use the filter[attributes] query parameter to specify Product Attributes that you want to include or exclude in the Product Projections response.

Include Attributes: specify the Attribute names to include them in the response.
Exclude Attributes: add a dash (-) before the Attribute names to exclude them from the response.

You can include or exclude Product Attributes, Attributes in the Master Variant, and all other variants of the Product.

Example queries:

Include only specific Attributesbash
curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/{id}?filter[attributes]=color&filter[attributes]=size -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

This returns only the color and size Attributes in the Product Projections response.

Exclude specific Attributesbash
curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/{id}?filter[attributes]=-description&filter[attributes]=-specifications -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

This returns all Attributes except description and specifications in the Product Projections response.

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 Search Term Suggestions, but is also considered for a full text search in the Product Projection Search API.
`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. Omitted when the Project has the ProductCatalogModel `Modular`. Use the Variant Projections API instead.
`variants` Array of ProductVariant	Additional Product Variants. Empty when the Project has the ProductCatalogModel `Modular`. Use the Variant Projections API instead.
`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. When projecting Prices by Store, the API supports only Embedded Prices (`Embedded`).
`attributes` Array of Attribute	Attributes according to the respective AttributeDefinition.
`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. Default: `20`Minimum: `0`Maximum: `500`
`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. Default: `0`Maximum: `10000`
`results` Array of ProductProjection	ProductProjections matching the query.

Get ProductProjection

Get ProductProjection by ID

GET

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

Retrieves the projected representation of a Product by its ID.

By default, this endpoint returns the current representation of Products where the published flag is true. If a Product is unpublished (published=false), the endpoint returns a Not Found error.

Required access scopes:

To retrieve the current representation of published Products (published data), the view_published_products:{projectKey} scope is required.
To retrieve the staged representation of Products (draft data) or access unpublished Products, the API Client must have the view_products:{projectKey} scope.

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	Enables Product price selection and Scoped Price Search. Pattern: `^[A-Z]{3}0?$`
`priceCountry` CountryCode	Enables Product price selection and Scoped Price Search. It can be used only in conjunction with the `priceCurrency` parameter. Pattern: `^[A-Z]{2}$`
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. It can be used only in conjunction with the `priceCurrency` parameter.
`priceCustomerGroupAssignments` String	IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups. It can be used only in conjunction with the `priceCurrency` parameter. The parameter can be passed multiple times.
`priceChannel` String	`id` of an existing Channel used for Product price selection. It can be used only in conjunction with the `priceCurrency` parameter.
`priceRecurrencePolicy` String	`id` of an existing RecurrencePolicy used for Product price selection. It can be used only 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 `languages`, `countries`, `distributionChannels`, or `supplyChannels`, they are used for projections based on locale, price, and inventory. If Product Selections are used, the API does not take the availability of the Product in the specified Store into account. Product Tailoring modifies the product information returned in API responses. However, you can only specify Query Predicates for the original Product data, not for the tailored data.
`filter[attributes]` String	Use for Attribute-based filtering. Specify Attribute names that you want to include or exclude from the response. To exclude an Attribute, add a dash (`-`) before the Attribute name. For example, `filter[attributes]=color&filter[attributes]=size` includes the `color` and `size` Attributes. And `filter[attributes]=-description&filter[attributes]=-specifications` excludes the `description` and `specifications` Attributes. If you specify multiple Attributes to be included and excluded from the response, then the Attributes you want to include are processed before the ones you want to exclude. The parameter can be passed multiple times.

Response:

200

ProductProjection

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

Get ProductProjection by Key

GET

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

Retrieves the projected representation of a Product by its Key.

Required access scopes:

To retrieve the current representation of published Products (published data), the view_published_products:{projectKey} scope is required.
To retrieve the staged representation of Products (draft data) or access unpublished Products, the API Client must have the view_products:{projectKey} scope.

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	Enables Product price selection and Scoped Price Search. Pattern: `^[A-Z]{3}0?$`
`priceCountry` CountryCode	Enables Product price selection and Scoped Price Search. It can be used only in conjunction with the `priceCurrency` parameter. Pattern: `^[A-Z]{2}$`
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. It can be used only in conjunction with the `priceCurrency` parameter.
`priceCustomerGroupAssignments` String	IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups. It can be used only in conjunction with the `priceCurrency` parameter. The parameter can be passed multiple times.
`priceChannel` String	`id` of an existing Channel used for Product price selection. It can be used only in conjunction with the `priceCurrency` parameter.
`priceRecurrencePolicy` String	`id` of an existing RecurrencePolicy used for Product price selection. It can be used only 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 `languages`, `countries`, `distributionChannels`, or `supplyChannels`, they are used for projections based on locale, price, and inventory. If Product Selections are used, the API does not take the availability of the Product in the specified Store into account. Product Tailoring modifies the product information returned in API responses. However, you can only specify Query Predicates for the original Product data, not for the tailored data.
`filter[attributes]` String	Use for Attribute-based filtering. Specify Attribute names that you want to include or exclude from the response. To exclude an Attribute, add a dash (`-`) before the Attribute name. For example, `filter[attributes]=color&filter[attributes]=size` includes the `color` and `size` Attributes. And `filter[attributes]=-description&filter[attributes]=-specifications` excludes the `description` and `specifications` Attributes. If you specify multiple Attributes to be included and excluded from the response, then the Attributes you want to include are processed before the ones you want to exclude. The parameter can be passed multiple times.

Response:

200

ProductProjection

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

Get ProductProjection in Store

Get ProductProjection in Store by ID

GET

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

Retrieves the projected 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. If a ProductTailoring exists for the Product with the given key and the given Store, this endpoint returns the ProductProjection with tailored data.

Required access scopes:

To retrieve the current representation of published Products (published data), the view_published_products:{projectKey} scope is required.
To retrieve the staged representation of Products (draft data) or access unpublished Products, the API Client must have the view_products:{projectKey} scope.

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	If `false`, this endpoint returns the current Product Projection if the Product is published, a ResourceNotFound error otherwise. this endpoint returns the ProductProjection with tailored Product information (if a ProductTailoring exists for the Product) when the ProductTailoring's `published` is `true`. this endpoint returns the ProductProjection with original Product information when the ProductTailoring's `published` is `false`. If `true`, this endpoint returns the staged Product Projection (only for API Clients that have the `view_products:{projectKey}` scope). this endpoint returns the ProductProjection with tailored Product information (if a ProductTailoring exists for the Product) when either the ProductTailoring's `published` or the ProductCatalogData `published` is `true`. If `published` is `false` for both ProductTailoring and ProductCatalogData, the ProductProjection contains original Product information. Default: `false`
`priceCurrency` CurrencyCode	Enables Product price selection and Scoped Price Search. Pattern: `^[A-Z]{3}0?$`
`priceCountry` CountryCode	Enables Product price selection and Scoped Price Search. It can be used only in conjunction with the `priceCurrency` parameter. Pattern: `^[A-Z]{2}$`
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. It can be used only in conjunction with the `priceCurrency` parameter.
`priceCustomerGroupAssignments` String	IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups. It can be used only in conjunction with the `priceCurrency` parameter. The parameter can be passed multiple times.
`priceChannel` String	`id` of an existing Channel used for Product price selection. It can be used only in conjunction with the `priceCurrency` parameter.
`priceRecurrencePolicy` String	`id` of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the `priceCurrency` parameter.
`localeProjection` Locale	Use for locale-based projection. The parameter can be passed multiple times.
`filter[attributes]` String	Use for Attribute-based filtering. Specify Attribute names that you want to include or exclude from the response. To exclude an Attribute, add a dash (`-`) before the Attribute name. For example, `filter[attributes]=color&filter[attributes]=size` includes the `color` and `size` Attributes. And `filter[attributes]=-description&filter[attributes]=-specifications` excludes the `description` and `specifications` Attributes. If you specify multiple Attributes to be included and excluded from the response, then the Attributes you want to include are processed before the ones you want to exclude. The parameter can be passed multiple times.

Response:

200

ProductProjection

application/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}

Retrieves the projected representation of a Product by its Key in the specified Store.

Required access scopes:

To retrieve the current representation of published Products (published data), the view_published_products:{projectKey} scope is required.
To retrieve the staged representation of Products (draft data) or access unpublished Products, the API Client must have the view_products:{projectKey} scope.

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	If `false`, this endpoint returns the current Product Projection if the Product is published, a ResourceNotFound error otherwise. this endpoint returns the ProductProjection with tailored Product information (if a ProductTailoring exists for the Product) when the ProductTailoring's `published` is `true`. this endpoint returns the ProductProjection with original Product information when the ProductTailoring's `published` is `false`. If `true`, this endpoint returns the staged Product Projection (only for API Clients that have the `view_products:{projectKey}` scope). this endpoint returns the ProductProjection with tailored Product information (if a ProductTailoring exists for the Product) when either the ProductTailoring's `published` or the ProductCatalogData `published` is `true`. If `published` is `false` for both ProductTailoring and ProductCatalogData, the ProductProjection contains original Product information. Default: `false`
`priceCurrency` CurrencyCode	Enables Product price selection and Scoped Price Search. Pattern: `^[A-Z]{3}0?$`
`priceCountry` CountryCode	Enables Product price selection and Scoped Price Search. It can be used only in conjunction with the `priceCurrency` parameter. Pattern: `^[A-Z]{2}$`
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. It can be used only in conjunction with the `priceCurrency` parameter.
`priceCustomerGroupAssignments` String	IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups. It can be used only in conjunction with the `priceCurrency` parameter. The parameter can be passed multiple times.
`priceChannel` String	`id` of an existing Channel used for Product price selection. It can be used only in conjunction with the `priceCurrency` parameter.
`priceRecurrencePolicy` String	`id` of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the `priceCurrency` parameter.
`localeProjection` Locale	Use for locale-based projection. The parameter can be passed multiple times.
`filter[attributes]` String	Use for Attribute-based filtering. Specify Attribute names that you want to include or exclude from the response. To exclude an Attribute, add a dash (`-`) before the Attribute name. For example, `filter[attributes]=color&filter[attributes]=size` includes the `color` and `size` Attributes. And `filter[attributes]=-description&filter[attributes]=-specifications` excludes the `description` and `specifications` Attributes. If you specify multiple Attributes to be included and excluded from the response, then the Attributes you want to include are processed before the ones you want to exclude. The parameter can be passed multiple times.

Response:

200

ProductProjection

application/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

You can sort the results only on standard scalar fields that are not nested inside arrays, such as masterVariant.sku, createdAt, and lastModifiedAt, as well as localized fields like name.en.

Sorting on Prices or on Attributes is not possible through the Query ProductProjections endpoint. To sort or filter on Attributes and for other product discovery use cases, use the Product Search API instead.

When querying an Attribute, we recommend that you use the performance-optimized Product Search API whenever possible. For more information, see inefficient patterns.

When querying an Attribute, you must always include both the attribute-name and attribute-value details in the Query Predicate. Otherwise, a 400 Bad Request error will occur.

GET

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

Retrieves the projected representation of Products by query predicates.

Required access scopes:

To retrieve the current representation of published Products (published data), the view_published_products:{projectKey} scope is required.
To retrieve the staged representation of Products (draft data) or access unpublished Products, the API Client must have the view_products:{projectKey} scope.

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.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested. Default: `20` Minimum: `0` Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0` Maximum: `10000`
`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	Enables Product price selection and Scoped Price Search. Pattern: `^[A-Z]{3}0?$`
`priceCountry` CountryCode	Enables Product price selection and Scoped Price Search. It can be used only in conjunction with the `priceCurrency` parameter. Pattern: `^[A-Z]{2}$`
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. It can be used only in conjunction with the `priceCurrency` parameter.
`priceCustomerGroupAssignments` String	IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups. It can be used only in conjunction with the `priceCurrency` parameter. The parameter can be passed multiple times.
`priceChannel` String	`id` of an existing Channel used for Product price selection. It can be used only in conjunction with the `priceCurrency` parameter.
`priceRecurrencePolicy` String	`id` of an existing RecurrencePolicy used for Product price selection. It can be used only 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 `languages`, `countries`, `distributionChannels`, or `supplyChannels`, they are used for projections based on locale, price, and inventory. If Product Selections are used, the API does not take the availability of the Product in the specified Store into account. Product Tailoring modifies the product information returned in API responses. However, you can only specify Query Predicates for the original Product data, not for the tailored data.
`filter[attributes]` String	Use for Attribute-based filtering. Specify Attribute names that you want to include or exclude from the response. To exclude an Attribute, add a dash (`-`) before the Attribute name. For example, `filter[attributes]=color&filter[attributes]=size` includes the `color` and `size` Attributes. And `filter[attributes]=-description&filter[attributes]=-specifications` excludes the `description` and `specifications` Attributes. If you specify multiple Attributes to be included and excluded from the response, then the Attributes you want to include are processed before the ones you want to exclude. The parameter can be passed multiple times.
`var.<varName>` String	Predicate parameter values. The parameter can be passed multiple times.

Response:

200

ProductProjectionPagedQueryResponse

application/json

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

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

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 with the provided id. Returns a 200 status if the ProductProjection exists, or a 404 status 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 with the provided key. Returns a 200 status if the ProductProjection exists, or a 404 status 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 the provided query predicate. Returns a 200 status if any ProductProjections match the query predicate, or a 404 status 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 with the provided id in the specified Store. Returns a 200 status if the ProductProjection exists, or a 404 status 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 with the provided key in the specified Store. Returns a 200 status if the ProductProjection exists, or a 404 status 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}"

Product Projections

Projection dimensions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Current / staged.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Publishing.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Unpublishing.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Locales.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Prices.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Projection by Store.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Projection by price selection.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Inventory entries.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Product Selection assignments.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Attributes.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ProductProjection.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ProductProjectionPagedQueryResponse.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get ProductProjection.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get ProductProjection by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get ProductProjection by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get ProductProjection in Store.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get ProductProjection in Store by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get ProductProjection in Store by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Query ProductProjections.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if ProductProjection exists.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if ProductProjection exists by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if ProductProjection exists by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if ProductProjection exists by Query Predicate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if ProductProjection exists in Store.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if ProductProjection exists in Store by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if ProductProjection exists in Store by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Projection dimensions

Current / staged

Publishing

Unpublishing

Locales

Prices

Projection by Store

Projection by price selection

Inventory entries

Product Selection assignments

Attributes

Representations

ProductProjection

ProductProjectionPagedQueryResponse

Get ProductProjection

Get ProductProjection by ID

Get ProductProjection by Key

Get ProductProjection in Store

Get ProductProjection in Store by ID

Get ProductProjection in Store by Key

Query ProductProjections

Check if ProductProjection exists

Check if ProductProjection exists by ID

Check if ProductProjection exists by Key

Check if ProductProjection exists by Query Predicate

Check if ProductProjection exists in Store

Check if ProductProjection exists in Store by ID

Check if ProductProjection exists in Store by Key