Product Selections

Manage individual Store assortments through Product Selections.

Product Selections can be used to manage individual assortments for different sales channels. For example, if you like to run multiple brand sites, sell your products in different countries, or operate a network of brick-and-mortar stores. This feature is useful for all those cases, in which the entire product catalog needs to be segmented into assortments that fit the respective sales channel.

Product Selections allow you to control the availability of a Product assortment by activation or deactivation of the respective Product Selection for a specific Store. Your shop frontend then queries only those Product Projections that are scoped to the corresponding Store.

Currently, the Product Projections Search API does not provide Store-specific search requests that are scoped to certain Product Selections, but in this guide we explain how an external search service can be integrated with the commercetools Platform to populate one search index per Store. Instead of this you can populate one search index per Product Selection that allows you to preview assortments that you are planning to launch soon, like the summer collection in a fashion store, before it goes live to the public.

The following diagram shows the relationship of the Product Selection entity to other entities on the commercetools Platform.

After you have created Product Selections and added Products to them, you can go ahead and assign them to one or several Stores.

You can then control the availability of a Product Selection via activation or deactivation of the Product Selection.

In case you have product assortments that are shared among Stores:

we recommend to have a separate Product Selection for the Products that the Stores have in common like illustrated in the figure below:

To find out which Products belong to a particular Product Selection, use the Query Products assigned to a Product Selection endpoints. For the opposite case, meaning to find out the Product Selections a particular Product belongs to, use the Query Product Selections for a Product endpoints.

Representations

ProductSelection

ProductSelectionDraft

ProductSelectionPagedQueryResponse

ProductSelectionReference

ProductSelectionTypeEnum

ProductSelectionProductPagedQueryResponse

ProductsInStorePagedQueryResponse

ProductSelectionAssignment

AssignedProductSelection

AssignedProductSelectionPagedQueryResponse

AssignedProductReference

IndividualProductSelectionType

ProductSelection

`id` String	Unique ID of the Product Selection.
`version` Int	Current version of the Product Selection.
`key` String	User-defined unique identifier for the Product Selection.
`createdAt` DateTime	Date and time (UTC) the Product Selection was initially created.
`createdBy` CreatedBy	Present on resources created after 1/02/2019 except for events not tracked.
`lastModifiedAt` DateTime	Date and time (UTC) the Product Selection was last updated.
`lastModifiedBy` LastModifiedBy	Present on resources updated after 1/02/2019 except for events not tracked.
`name` LocalizedString	Name of the Product Selection.
`productCount` Int	Number of Products that are currently assigned to this Product Selection.
`type` ProductSelectionTypeEnum	Specifies in which way the Products are assigned to the Product Selection. Currently, the only way of doing this is to specify each Product individually. Hence, the type is fixed to `individual` for now, but we have plans to add other types in the future.

ProductSelectionDraft

`key` String	User-defined unique identifier for the Product Selection. You can use `key` besides `ID` to reference the Product Selection.
`name` LocalizedString	Name of the Product Selection. Not checked for uniqueness, but distinct names are recommended.

ProductSelectionPagedQueryResponse

PagedQueryResult containing an array of ProductSelection.

`limit` Int	Number of results requested in the query request.
`offset` Int	Offset supplied by the client or the server default. It is the number of elements skipped, not a page number.
`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. Unlike other endpoints, the Product Selection endpoint does not return this field by default. To get `total`, pass the query parameter `withTotal` set to `true`. When the results are filtered with a Query Predicate, `total` is subject to a limit.
`results` Array of ProductSelection	The Product Selections matching the query.

ProductSelectionReference

`id` String	Unique ID of the Product Selection.
`typeId` String	`"product-selection"`
`obj` ProductSelection	Contains the representation of the expanded Product Selection. Only present in responses to requests with Reference Expansion for Product Selection.

ProductSelectionTypeEnum

The following type of Product Selections is supported:

individual: For this type of Product Selections the Products are to be assigned individually by using the Add Product update action.

ProductSelectionProductPagedQueryResponse

PagedQueryResult containing an array of AssignedProductReference.

`limit` Int	Number of results requested in the query request.
`offset` Int	Offset supplied by the client or the server default. It is the number of elements skipped, not a page number.
`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. Unlike other endpoints, the Product Selection endpoint does not return this field by default. To get `total`, pass the query parameter `withTotal` set to `true`. When the results are filtered with a Query Predicate, `total` is subject to a limit.
`results` Array of AssignedProductReference	References to Products that are assigned to the Product Selection.

ProductsInStorePagedQueryResponse

PagedQueryResult containing an array of ProductSelectionAssignment.

`limit` Int	Number of results requested in the query request.
`offset` Int	Offset supplied by the client or the server default. It is the number of elements skipped, not a page number.
`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. Unlike other endpoints, the Product Selection endpoint does not return this field by default. To get `total`, pass the query parameter `withTotal` set to `true`. When the results are filtered with a Query Predicate, `total` is subject to a limit.
`results` Array of ProductSelectionAssignment	Product Selection Assignments.

ProductSelectionAssignment

Specifies which Product is assigned to which Product Selection.

`product` ProductReference	Reference to a Product that is assigned to the Product Selection.
`productSelection` ProductSelectionReference	Reference to the Product Selection that this assignment is part of.

AssignedProductSelection

productSelection

ProductSelectionReference

Reference to the Product Selection that this assignment is part of.

AssignedProductSelectionPagedQueryResponse

PagedQueryResult containing an array of AssignedProductSelection.

`limit` Int	Number of results requested in the query request.
`offset` Int	Offset supplied by the client or the server default. It is the number of elements skipped, not a page number.
`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. Unlike other endpoints, the Product Selection endpoint does not return this field by default. To get `total`, pass the query parameter `withTotal` set to `true`. When the results are filtered with a Query Predicate, `total` is subject to a limit.
`results` Array of AssignedProductSelection	References to Product Selection that are assigned to the Product.

AssignedProductReference

product

ProductReference

Reference to a Product that is assigned to the Product Selection.

IndividualProductSelectionType

`type` String	`"individual"` For this type of Product Selections the Products are to be assigned individually by using the Add Product update action.
`name` LocalizedString	The name of the Product Selection which is recommended to be unique.

Get Product Selection

Get Product Selection by ID

GET

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

OAuth 2.0 Scopes:

view_product_selections:{projectKey}

Path parameters:

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

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200ProductSelection

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/product-selections/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Get Product Selection by Key

GET

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

OAuth 2.0 Scopes:

view_product_selections:{projectKey}

Path parameters:

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

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200ProductSelection

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/product-selections/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Query Product Selections

GET

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

OAuth 2.0 Scopes:

view_product_selections:{projectKey}

Path parameters:

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

Query parameters:

`where` QueryPredicate	The parameter can be passed multiple times.
`/^var[.][a-zA-Z0-9]+$/` Any string parameter matching this regular expression	Predicate parameter values. The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results returned.
`offset` Int	Number of results 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.

Response:

200ProductSelectionPagedQueryResponse

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/product-selections -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Query Products assigned to a Product Selection

by ID

By default, the response does not include the total field. To get total included, pass the query parameter withTotal set to true.

GET

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

OAuth 2.0 Scopes:

view_product_selections:{projectKey}

Path parameters:

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

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results returned.
`offset` Int	Number of results 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.

Response:

200ProductSelectionProductPagedQueryResponse

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/product-selections/{id}/products -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

by Key

By default, the response does not include the total field. To get total included, pass the query parameter withTotal set to true.

GET

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

OAuth 2.0 Scopes:

view_product_selections:{projectKey}

Path parameters:

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

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results returned.
`offset` Int	Number of results 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.

Response:

200ProductSelectionProductPagedQueryResponse

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/product-selections/key={key}/products -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Query Products available in a Store through active Product Selections

The response will include duplicate Products whenever more than one active Product Selection of the Store includes a Product. To make clear through which Product Selection a Product is available in the Store the response contains assignments including both the Product and the Product Selection. Only Products of Product Selections that are activated in Store will be returned.

By default, the response does not include the total field. To get total included, pass the query parameter withTotal set to true.

Queries Product Selection assignments in a specific Store.

GET

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

OAuth 2.0 Scopes:

view_product_selections:{projectKey}

Path parameters:

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

Response:

200ProductsInStorePagedQueryResponse

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-selection-assignments -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create Product Selection

POST

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

OAuth 2.0 Scopes:

manage_product_selections:{projectKey}

Path parameters:

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

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:ProductSelectionDraft

Response:

201ProductSelection

Request Example:cURL

curl -X POST https://api.{region}.commercetools.com/{projectKey}/product-selections -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "key" : "finest-selection",
  "name" : {
    "en" : "Finest Selection"
  }
}
DATA

Update Product Selection

Update Product Selection by ID

POST

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

OAuth 2.0 Scopes:

manage_product_selections:{projectKey}

Path parameters:

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

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:

`version` Int
`actions` Array of ProductSelectionUpdateAction

Response:

200ProductSelection

Request Example:cURL

curl -X POST https://api.{region}.commercetools.com/{projectKey}/product-selections/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "changeName",
    "name" : {
      "en" : "new selection name"
    }
  } ]
}
DATA

Update Product Selection by Key

POST

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

OAuth 2.0 Scopes:

manage_product_selections:{projectKey}

Path parameters:

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

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:

`version` Int
`actions` Array of ProductSelectionUpdateAction

Response:

200ProductSelection

Request Example:cURL

curl -X POST https://api.{region}.commercetools.com/{projectKey}/product-selections/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "changeName",
    "name" : {
      "en" : "new selection name"
    }
  } ]
}
DATA

Update actions

Add Product

`action` String	`"addProduct"`
`product` ProductResourceIdentifier	ResourceIdentifier to Product

Example: json

{
  "action" : "addProduct",
  "product" : {
    "typeId" : "product",
    "key" : "millennium-falcon"
  }
}

Remove Product

`action` String	`"removeProduct"`
`product` ProductResourceIdentifier	ResourceIdentifier to Product

Example: json

{
  "action" : "removeProduct",
  "product" : {
    "typeId" : "product",
    "key" : "millennium-falcon"
  }
}

Set Key

`key` String	If `key` is absent or `null`, the existing key, if any, will be removed.
`action` String	`"setKey"`

Example: json

{
  "action" : "setKey",
  "key" : "ProductSelectionKey"
}

Change Name

`action` String	`"changeName"`
`name` LocalizedString	The new name to be set for the Product Selection.

Example: json

{
  "action" : "changeName",
  "name" : {
    "en" : "My Product Selection",
    "de" : "Meine Product Selection"
  }
}

Delete Product Selection

Delete Product Selection by ID

Deletion will only succeed if the Product Selection is not assigned to any Store.

DELETE

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

OAuth 2.0 Scopes:

manage_product_selections:{projectKey}

Path parameters:

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

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`version` Int	Last seen version of the resource.

Response:

200ProductSelection

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/product-selections/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Delete Product Selection by Key

Deletion will only succeed if the Product Selection is not assigned to any Store.

DELETE

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

OAuth 2.0 Scopes:

manage_product_selections:{projectKey}

Path parameters:

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

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`version` Int	Last seen version of the resource.

Response:

200ProductSelection

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/product-selections/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'