BETA

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.

Product Selections related to Stores and Products

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:

assortment overlap

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

Separate Product Selection

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

id
String

Platform-generated unique identifier of the ProductSelection.

version
Int

Current version of the ProductSelection.

key
String

User-defined unique identifier of the ProductSelection.

createdAt

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

createdBy

Present on resources created after 1/02/2019 except for events not tracked.

lastModifiedAt

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

lastModifiedBy

Present on resources updated after 1/02/2019 except for events not tracked.

name

Name of the ProductSelection.

productCount
Int

Number of Products that are currently assigned to this ProductSelection.

type

Specifies in which way the Products are assigned to the ProductSelection. 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.

custom

Custom Fields of this ProductSelection.

ProductSelectionDraft

key
String

User-defined unique identifier for the ProductSelection.

name

Name of the ProductSelection. Not checked for uniqueness, but distinct names are recommended.

custom

Custom Fields of this ProductSelection.

ProductSelectionPagedQueryResponse

PagedQueryResult containing an array of ProductSelection.

limit
Int

Number of results requested.

offset
Int

Number of elements skipped.

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

ProductSelections matching the query.

ProductSelectionReference

id
String

Platform-generated unique identifier of the referenced ProductSelection.

typeId
String
"product-selection"

References a ProductSelection.

obj

Contains the representation of the expanded ProductSelection. Only present in responses to requests with Reference Expansion for ProductSelections.

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

limit
Int

Number of results requested.

offset
Int

Number of elements skipped.

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

References to Products that are assigned to the ProductSelection.

ProductsInStorePagedQueryResponse

limit
Int

Number of results requested.

offset
Int

Number of elements skipped.

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

ProductSelectionAssignments matching the query.

ProductSelectionAssignment

Specifies which Product is assigned to which ProductSelection.

product

Reference to a Product that is assigned to the ProductSelection.

productSelection

Reference to the ProductSelection that this assignment is part of.

AssignedProductSelection

productSelection

Reference to the ProductSelection that this assignment is part of.

AssignedProductSelectionPagedQueryResponse

limit
Int

Number of results requested.

offset
Int

Number of elements skipped.

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

References to ProductSelection that are assigned to the Product.

AssignedProductReference

product

Reference to a Product that is assigned to the ProductSelection.

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

The name of the ProductSelection 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
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
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
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.

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

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

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.

Query parameters:
expand
The parameter can be passed multiple times.
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
The parameter can be passed multiple times.
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
The parameter can be passed multiple times.
Request Body:
version
Int
actions
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
The parameter can be passed multiple times.
Request Body:
version
Int
actions
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

ResourceIdentifier to Product

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

Remove Product

action
String
"removeProduct"
product

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

The new name to be set for the ProductSelection.

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

Set Custom Type

action
String
"setCustomType"
type

Defines the Type that extends the ProductSelection with Custom Fields. If absent, any existing Type and Custom Fields are removed from the ProductSelection.

fields

Sets the Custom Fields fields for the ProductSelection.

Example: json
{
"action" : "setCustomType",
"type" : {
"id" : "{{type-id}}",
"typeId" : "type"
},
"fields" : {
"examplaryStringTypeField" : "TextString"
}
}

Set CustomField

action
String
"setCustomField"
name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action" : "setCustomField",
"name" : "ExamplaryStringTypeField",
"value" : "TextString"
}

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
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
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}'
Developer Center
HTTP APIGraphQL APIPlatform Release NotesCustom ApplicationsBETASDKs & Client LibrariesImport & ExportSUNRISE Starter FrontendsTutorialsFAQ
Merchant Center
DocumentationRelease Notes
Sign upLog inTech BlogIntegrationsStatusSupportUser Research Program
Copyright © 2022 commercetools
Privacy PolicyImprint