Product Projections

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

The query endpoint provides 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.

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 a 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

id
String

Unique identifier of the Product.

version
Int

Current version of the Product.

key
String

User-defined unique identifier of the Product.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
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 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

The Master Variant of the Product.

variants
Array of ProductVariant

Additional Product Variants.

taxCategory

The TaxCategory of the Product.

state

State of the Product.

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.

createdAt

Date and time (UTC) the ProductProjection was initially created.

lastModifiedAt

Date and time (UTC) the ProductProjection was last updated.

ProductProjectionPagedQueryResponse

limit
Int
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
Query parameters:
expand
The parameter can be passed multiple times.
staged
Boolean

Defaults to false. Set to true to retrieve the staged Product Projection (only for API Clients that have the view_products:{projectKey} scope).

priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used 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.

Response:
Request Example:cURL
curl -X 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
The parameter can be passed multiple times.
staged
Boolean

Defaults to false. Set to true to retrieve the staged Product Projection (only for API Clients that have the view_products:{projectKey} scope).

priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used 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.

Response:
Request Example:cURL
curl -X 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 a Store BETA

Get ProductProjection in a Store by ID BETA

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 from the specified Store. If the Store has defined some languages, countries, distribution or supply Channels, they are used for projections based on locale, price and inventory.

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
Query parameters:
expand
The parameter can be passed multiple times.
staged
Boolean

Defaults to false. Set to true to retrieve the staged Product Projection (only for API Clients that have the view_products:{projectKey} scope).

priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used for locale-based projection.

The parameter can be passed multiple times.
Response:
Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Get ProductProjection in a Store by Key BETA

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 from the specified Store. If the Store has defined some languages, countries, distribution or supply Channels, they are used for projections based on locale, price and inventory.

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
The parameter can be passed multiple times.
staged
Boolean

Defaults to false. Set to true to retrieve the staged Product Projection (only for API Clients that have the view_products:{projectKey} scope).

priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used for locale-based projection.

The parameter can be passed multiple times.
Response:
Request Example:cURL
curl -X 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 Search Product Projections 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
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
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
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.

staged
Boolean

Defaults to false. Set to true to retrieve the staged Product Projection (only for API Clients that have the view_products:{projectKey} scope).

priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used 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.

Request Example:cURL
curl -X 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"
} ]
}