Projection dimensions
Current / staged
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
- Locales defined directly with the query parameter
localeProjection
. - Locales configured in the Store that is specified with the query parameter
storeProjection
.
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
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
storeProjection
.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.
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.
prices
array within the Product Projection.Projection by price selection
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
storeProjection
.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
Product Selection assignments
Representations
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 | The ProductType defining the Attributes of the Product. |
name | Name of the Product. |
description | Description of the Product. |
slug | 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 | Order of Product in Categories. |
metaTitle | Title of the Product displayed in search results. |
metaDescription | Description of the Product displayed in search results below the meta title. |
metaKeywords | Keywords that give additional information about the Product to search engines. |
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 | |
masterVariant | The Master Variant of the Product. |
variants Array of ProductVariant | Additional Product Variants. |
taxCategory | The TaxCategory of the Product. |
state | |
reviewRatingStatistics | Review statistics of the Product. |
priceMode | 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 . |
attributes BETAArray 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
view_published_products:{projectKey}
scope, this endpoint only returns published (current) Product Projections.view_products:{projectKey}
view_published_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
id String | id of the ProductProjection. |
expand | 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 | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | 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 | 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. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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",
"attributes": []
}
Get ProductProjection by Key
view_published_products:{projectKey}
scope,
this endpoint only returns published (current) Product Projections.view_products:{projectKey}
view_published_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
key String | key of the ProductProjection. |
expand | 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 | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | 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 | 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. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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",
"attributes": []
}
Get ProductProjection in Store
Get ProductProjection in Store by ID
id
and the given Store, this endpoint returns the ProductProjection with tailored data.view_published_products:{projectKey}
scope, this endpoint only returns published (current) Product Projections.view_products:{projectKey}
view_published_products:{projectKey}
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. |
expand | The parameter can be passed multiple times. |
staged Boolean | If
false ,
If
true ,
Default: false |
priceCurrency | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | 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 | Use for locale-based projection. The parameter can be passed multiple times. |
application/json
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
key
and the given Store, this endpoint returns the ProductProjection with tailored data.view_published_products:{projectKey}
scope, this endpoint only returns published (current) Product Projections.view_products:{projectKey}
view_published_products:{projectKey}
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. |
expand | The parameter can be passed multiple times. |
staged Boolean | If
false ,
If
true ,
Default: false |
priceCurrency | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | 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 | Use for locale-based projection. The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Query ProductProjections
attribute-name
and attribute-value
details in the Query Predicate. Otherwise, a 400 Bad Request error will occur.view_published_products:{projectKey}
scope,
this endpoint only returns published (current) Product Projections.view_products:{projectKey}
view_published_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
where | The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | 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 | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | 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 | 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. |
var.<varName> String | Predicate parameter values. The parameter can be passed multiple times. |
ProductProjectionPagedQueryResponse
asapplication/json
curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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",
"attributes": []
},
{
"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",
"attributes": []
}
]
}
Check if ProductProjection exists
Check if ProductProjection exists by ID
id
. Returns a 200
status if the ProductProjection exists, or a 404
status otherwise.view_products:{projectKey}
view_published_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
id String | id of the ProductProjection. |
curl --head https://api.{region}.commercetools.com/{projectKey}/product-projections/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if ProductProjection exists by Key
key
. Returns a 200
status if the ProductProjection exists, or a 404
status otherwise.view_products:{projectKey}
view_published_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
key String | key of the ProductProjection. |
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
200
status if any ProductProjections match the query predicate, or a 404
status otherwise.view_products:{projectKey}
view_published_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
where | The parameter can be passed multiple times. |
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
id
in the specified Store. Returns a 200
status if the ProductProjection exists, or a 404
status otherwise.view_products:{projectKey}
view_published_products:{projectKey}
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. |
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
key
in the specified Store. Returns a 200
status if the ProductProjection exists, or a 404
status otherwise.view_products:{projectKey}
view_published_products:{projectKey}
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. |
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"