Product Projections

B2CB2BB2XPRODUCT CATALOGAgenticLift

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. For what Product Projections are and how they behave, see Product catalog overview. For rules that apply across the Product catalog APIs, see Product catalog APIs overview.
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:
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

You can apply the following projection dimensions with the Product Projections API and the Products API by using query parameters. For the rules of each projection dimension, and for how the query parameters map to the GraphQL API, see Product catalog APIs overview.

Current / staged

To choose between the current and staged projection, use the staged query parameter on the Product Projections endpoints. These endpoints request the current projection by default because it's the typical use case for Customer-facing storefronts.
For which projections a Product has, and what publishing and unpublishing change, see Product catalog APIs overview.

Locales

To project by locale, use the localeProjection query parameter. To use the locales configured in a Store, use the storeProjection query parameter.
For the order in which these locales are determined, and how the API falls back when a translation is missing, see Product catalog APIs overview.

Prices

The Product Projections API supports two ways to work with Prices:

Projection by Store

To project Embedded Prices by the distribution Channels and countries of a Store, use the storeProjection query parameter.
For which Prices are included, see Product catalog APIs overview.

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.
  • Product price selection: When displaying a price on a product detail page, the price is determined by the Product Projections API and the Product Projection Search API based on the following parameters:
    • priceCurrency: maps to value.currencyCode of Price or StandalonePrice
    • priceCustomerGroup: maps to customerGroup of Price or StandalonePrice
    • priceChannel: maps to channel of Price or StandalonePrice
    • priceCountry: maps to country of Price or StandalonePrice
    • priceRecurrencePolicy: maps to recurrencePolicy of Price or StandalonePrice
    • priceCustomerGroupAssignments: maps to customerGroup of Price or StandalonePrice. For more information, see Fallback logic for multiple Customer Groups.
      Product Projection Search does not support multiple Customer Group prices.

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 project Product Variant Availabilities by the Inventory supply Channels of a Store, use the storeProjection query parameter.
For which Inventory entries are included, see Product catalog APIs overview.

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 which Product Variants and Categories these endpoints return, see Product Variants in Store and Categories in Store.

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.

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
​
String
​

Use to expand resources in a single request.

For more information, see Reference 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

as
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
{
  "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

GET
https://api.{region}.commercetools.com/{projectKey}/product-projections/key={key}
Retrieves the projected representation of a Product by its Key.
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.
key
​
String
​
key of the ProductProjection.
Query parameters:
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference 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

as
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
{
  "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

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.
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.
storeKey
​
String
​
key of the Store.
id
​
String
​
id of the ProductProjection.
Query parameters:
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference 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

as
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.
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.
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.
storeKey
​
String
​
key of the Store.
key
​
String
​
key of the ProductProjection.
Query parameters:
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference 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

as
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.
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.
Query parameters:
where
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
The parameter can be passed multiple times.
sort
​
String
​

Use to sort query results.

For more information, see Sorting.
The parameter can be passed multiple times.
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
limit
​
Int32
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int32
​
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

as
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
{
  "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

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
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
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}"

Representations

ProductProjection

id​
String​
Unique identifier of the Product.
version​
Int64​
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​

Whether the staged data is different from the current data.

published​
Boolean​
Whether 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​
Int64​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
count​
Int64​

Actual number of results returned.

total​
Int64​
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​
Int64​
Number of elements skipped.
Default: 0​Maximum: 10000​
results​
Array of ProductProjection​
ProductProjections matching the query.