Documentation

Product Selections

Elevate, May 20-22-2025, Miami Beach, Florida

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.

commercetools Composable Commerce offers two modes of Product Selections specifying a subset of your Project's product catalog. In both modes, you specify each Product individually, but you either include the Products or exclude them explicitly, whichever is more convenient for you.

  • Individual: each Product that should be part of the Product Selection is added explicitly.
  • IndividualExclusion: each Product that should not be part of the Product Selection is excluded explicitly.
Product Selections allow you to control the availability of a Product assortment by activating or deactivating 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 with the Product Search API you can query if a Product belongs to a specific Product Selection or Store. Currently, Product Variant Selections are not supported.
To learn more, see the Model assortments with Product Selections tutorial.
The guide Populating a Store-specific external search explains how to integrate an external search service with commercetools Composable Commerce to populate a search index per store. Alternatively, you can populate one search index per Product Selection. This approach allows you to preview upcoming assortments, such as the summer collection in a fashion store, before publishing them to your customers.

The following diagram shows the relationship of the Product Selection entity to other entities on the Composable Commerce APIs.

Product Selections related to Stores and Products

Our recommended workflow when using Product Selections is the following:

  1. create initial set of Products with their Variants.
  2. create Product Selections.
  3. assign Products and optionally Product Variants to the Product Selections.
If you created the Product Selections together with ProductVariantSelections before the actual Products with their respective SKUs, you would risk losing the related ProductSelectionAssignments due to a background service cleaning up non-existing SKUs.
After you have created a Product Selection and added Products and Variants to it, you can go ahead and assign it 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 like

assortment overlap

we recommend creating a separate, shared Product Selection for the Products that the Stores have in common:

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​

Unique identifier of the ProductSelection.

version​
Int​

Current version of the ProductSelection.

key​
String​

User-defined unique identifier of the ProductSelection.

name​
LocalizedString​

Name of the ProductSelection.

productCount​
Int​

Number of Products that are currently assigned to this ProductSelection.

mode​
ProductSelectionMode​
Specifies in which way the Products are assigned to the ProductSelection. Currently, the only way of doing this is to specify each Product individually, either by including or excluding them explicitly.
Default: Individual​
custom​
CustomFields​

Custom Fields of the ProductSelection.

createdAt​
DateTime​

Date and time (UTC) the ProductSelection 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 ProductSelection was last updated.

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

ProductSelectionDraft

key​
String​

User-defined unique identifier for the ProductSelection.

name​
LocalizedString​

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

mode​
ProductSelectionMode​

Mode of the Product Selection.

Default: Individual​
custom​
CustomFieldsDraft​

Custom Fields of this ProductSelection.

ProductSelectionPagedQueryResponse

PagedQueryResult containing an array of ProductSelection.
limit​
Int​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​
Number of elements skipped.
Default: 0​Maximum: 10000​
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.
results​
Array of ProductSelection​
ProductSelections matching the query.

ProductSelectionReference

Reference to a ProductSelection.
id​
String​
Unique identifier of the referenced ProductSelection.
typeId​
ReferenceTypeId​
product-selection

Type of referenced resource.

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

ProductSelectionResourceIdentifier

ResourceIdentifier to a ProductSelection. Either id or key is required. If both are set, an InvalidJsonInput error is returned.
id​
String​
Unique identifier of the referenced ProductSelection. Required if key is absent.
key​
String​
User-defined unique identifier of the referenced ProductSelection. Required if id is absent.
typeId​
ReferenceTypeId​
product-selection
Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

ProductSelectionMode

Product Selections can have the following modes:

Individual
For this mode of Product Selection, the Products are to be assigned individually by using the Add Product update action.
IndividualExclusion
Defines the Product Selection to contain Products that are excluded from the catalog. For this mode of Product Selection, the Products are to be excluded individually by using the Exclude Product update action.

ProductSelectionProductPagedQueryResponse

PagedQueryResult containing an array of AssignedProductReference.
limit​
Int​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​
Number of elements skipped.
Default: 0​Maximum: 10000​
count​
Int​

Actual number of results returned.

total​
Int​
Total number of results matching the query. Present only when the withTotal query parameter is set to true. This number is an estimation that is not strongly consistent. 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 ProductSelection.

ProductsInStorePagedQueryResponse

PagedQueryResult containing an array of ProductSelectionAssignment.
limit​
Int​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​
Number of elements skipped.
Default: 0​Maximum: 10000​
count​
Int​

Actual number of results returned.

total​
Int​
Total number of results matching the query. Present only when the withTotal query parameter is set to true. This number is an estimation that is not strongly consistent. When the results are filtered with a Query Predicate, total is subject to a limit.
results​
Array of ProductSelectionAssignment​

ProductSelectionAssignments matching the query.

ProductSelectionAssignment

Specifies which Product is assigned to which ProductSelection.

The entire ProductSelectionAssignment is deleted automatically with eventual consistency if all of the SKUs have been removed from a ProductVariantSelection IncludeOnly or from a ProductVariantExclusion.
For ProductVariantSelection IncludeAllExcept only the variantSelection of the ProductSelectionAssignment is deleted in such case, meaning that all SKUs of the respective Product are included then.
The above also applies if the Product Variants with the corresponding SKUs have been removed from their Product.

Given the mode of Product Selection, this assignment refers to, it may contain:

product​
ProductReference​

Reference to a Product that is assigned to the ProductSelection.

productSelection​
ProductSelectionReference​

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

variantSelection​
ProductVariantSelection​

Defines which particular Variants of the Product are included in the Product Selection. If undefined all Variants of the referenced Product are included.

This field is only available for assignments to a Product Selection with Individual ProductSelectionMode. The list of SKUs will be updated automatically on any change of those performed on the respective Product itself.
variantExclusion​
ProductVariantExclusion​

Defines which particular Variants of the Product are excluded from the Product Selection. If undefined all Variants of the referenced Product are excluded.

This field is only available for assignments to a Product Selection with IndividualExclusion ProductSelectionMode. The list of SKUs will be updated automatically on any change of those performed on the respective Product itself.

AssignedProductSelection

productSelection​
ProductSelectionReference​

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

variantSelection​
ProductVariantSelection​

Defines which Variants of the Product will be included in the Product Selection.

This field is only available for assignments to a Product Selection with Individual ProductSelectionMode.
variantExclusion​
ProductVariantExclusion​

Defines which Variants of the Product will be excluded from the Product Selection.

This field is only available for assignments to a Product Selection with IndividualExclusion ProductSelectionMode.
createdAt​
DateTime​

Date and time (UTC) this assignment was initially created.

AssignedProductSelectionPagedQueryResponse

PagedQueryResult containing an array of AssignedProductSelection.
limit​
Int​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​
Number of elements skipped.
Default: 0​Maximum: 10000​
count​
Int​

Actual number of results returned.

total​
Int​
Total number of results matching the query. Present only when the withTotal query parameter is set to true. This number is an estimation that is not strongly consistent. When the results are filtered with a Query Predicate, total is subject to a limit.
results​
Array of AssignedProductSelection​

References to ProductSelection that are assigned to the Product.

AssignedProductReference

product​
ProductReference​

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

variantSelection​
ProductVariantSelection​

The Variants of the Product that are included from the Product Selection.

This field may exist only in Product Selections with Individual ProductSelectionMode. In absence of this field, all Variants are deemed to be included.
variantExclusion​
ProductVariantExclusion​

The Variants of the Product that are excluded from the Product Selection.

This field may exist only in Product Selections with IndividualExclusion ProductSelectionMode. In absence of this field, all Variants are deemed to be excluded.

ProductVariantSelection

Polymorphic base type that determines if a Product Selection can include only specified SKUs or include all except specified SKUs.
A background process takes care that SKUs deleted on Products are removed from the skus field of the ProductVariantSelection automatically, making sure no ProductSelectionAssignment contains any outdated SKU.

ProductVariantSelection IncludeOnly

Only Product Variants with explicitly stated SKUs are part of the Product Selection.

type​
ProductVariantSelectionTypeEnum​
includeOnly
skus​
Array of String​

Non-empty array of SKUs representing Product Variants to be included into the Product Selection.

ProductVariantSelection IncludeAllExcept

All Product Variants except the explicitly stated SKUs are part of the Product Selection.

type​
ProductVariantSelectionTypeEnum​
includeAllExcept
skus​
Array of String​

Non-empty array of SKUs representing Product Variants to be excluded from the Product Selection.

ProductVariantExclusion

Only Product Variants with the explicitly listed SKUs are part of a Product Selection with IndividualExclusion ProductSelectionMode.
skus​
Array of String​
Non-empty array of SKUs representing Product Variants to be included in the Product Selection with IndividualExclusion ProductSelectionMode.

Get ProductSelection

Get ProductSelection 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:
200

ProductSelection

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/product-selections/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ProductSelectionjson
{
  "mode": "Individual",
  "id": "dbd58c4a-7b2c-4b45-8134-c95bfd322d05",
  "version": 1,
  "createdAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "key": "finest-selection",
  "name": {
    "en": "Finest Selection"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
    },
    "fields": {
      "description": "my description"
    }
  },
  "productCount": 909
}

Get ProductSelection 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:
200

ProductSelection

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/product-selections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ProductSelectionjson
{
  "mode": "Individual",
  "id": "dbd58c4a-7b2c-4b45-8134-c95bfd322d05",
  "version": 1,
  "createdAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "key": "finest-selection",
  "name": {
    "en": "Finest Selection"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
    },
    "fields": {
      "description": "my description"
    }
  },
  "productCount": 909
}

Query ProductSelections

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.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
withTotal
​
Boolean
​
Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.
Default: true​
var.<varName>
​
String
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

ProductSelectionPagedQueryResponse

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/product-selections -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ProductSelectionPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 2,
  "total": 2,
  "results": [
    {
      "mode": "Individual",
      "id": "4b984295-82e7-4404-aa68-467a12f10ba9",
      "version": 5,
      "createdAt": "2021-06-23T09:33:21.010Z",
      "lastModifiedAt": "2021-06-24T12:07:21.326Z",
      "lastModifiedBy": {
        "isPlatformClient": true,
        "user": {
          "typeId": "user",
          "id": "4cd2cb89-7d23-4306-87a4-1d8b0db3845d"
        }
      },
      "createdBy": {
        "isPlatformClient": true,
        "user": {
          "typeId": "user",
          "id": "4cd2cb89-7d23-4306-87a4-1d8b0db3845d"
        }
      },
      "key": "my-selection",
      "name": {
        "en": "My Product Selection"
      },
      "custom": {
        "type": {
          "typeId": "type",
          "id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
        },
        "fields": {
          "description": "my description"
        }
      },
      "productCount": 0
    },
    {
      "mode": "Individual",
      "id": "dbd58c4a-7b2c-4b45-8134-c95bfd322d05",
      "version": 1,
      "createdAt": "2021-06-27T10:12:16.154Z",
      "lastModifiedAt": "2021-06-27T10:12:16.154Z",
      "lastModifiedBy": {
        "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
        "isPlatformClient": false
      },
      "createdBy": {
        "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
        "isPlatformClient": false
      },
      "key": "finest-selection",
      "name": {
        "en": "Finest Selection"
      },
      "productCount": 1
    }
  ]
}

Query Products assigned to a ProductSelection

by ProductSelection 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:
where
​
QueryPredicate
​
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 requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
withTotal
​
Boolean
​
Controls the calculation of the total number of query results. Set to true to get the total number of query results. This may impact query performance.
Default: false​
Response:
200

ProductSelectionProductPagedQueryResponse

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/product-selections/{id}/products -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ProductSelectionProductPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 2,
  "results": [
    {
      "product": {
        "typeId": "product",
        "id": "72dcfd13-92e8-4fa1-bd01-926a646bfb30"
      },
      "variantSelection": {
        "type": "includeOnly",
        "skus": ["M0E20000000E1PI"]
      }
    },
    {
      "product": {
        "typeId": "product",
        "id": "2a38796b-0bb1-4a4f-8b0d-bf6e8f6661a7"
      },
      "variantSelection": {
        "type": "includeOnly",
        "skus": ["M0E20000000E1PJ"]
      }
    }
  ]
}

by ProductSelection 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:
where
​
QueryPredicate
​
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 requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
withTotal
​
Boolean
​
Controls the calculation of the total number of query results. Set to true to get the total number of query results. This may impact query performance.
Default: false​
Response:
200

ProductSelectionProductPagedQueryResponse

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/product-selections/key={key}/products -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ProductSelectionProductPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 2,
  "results": [
    {
      "product": {
        "typeId": "product",
        "id": "72dcfd13-92e8-4fa1-bd01-926a646bfb30"
      },
      "variantSelection": {
        "type": "includeOnly",
        "skus": ["M0E20000000E1PI"]
      }
    },
    {
      "product": {
        "typeId": "product",
        "id": "2a38796b-0bb1-4a4f-8b0d-bf6e8f6661a7"
      },
      "variantSelection": {
        "type": "includeOnly",
        "skus": ["M0E20000000E1PJ"]
      }
    }
  ]
}

Query Products assigned to active ProductSelections in a Store

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-selection-assignments
Queries Product Selection assignments in a specific Store.

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 the Store will be returned.

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:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
withTotal
​
Boolean
​
Controls the calculation of the total number of query results. Set to true to get the total number of query results. This may impact query performance.
Default: false​
var.<varName>
​
String
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

ProductsInStorePagedQueryResponse

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-selection-assignments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ProductsInStorePagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "results": [
    {
      "productSelection": {
        "id": "3a914b5c-4b87-42ce-998c-91e5aa7a329f",
        "typeId": "product-selection"
      },
      "product": {
        "id": "d1c99e83-b9d4-48b2-9441-108c2a47009b",
        "typeId": "product"
      }
    }
  ]
}

Check if ProductSelection exists

Check if ProductSelection exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/product-selections/{id}
Checks if a ProductSelection exists with the provided id. Returns a 200 OK status if the ProductSelection exists or a 404 Not Found otherwise.
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.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/product-selections/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if ProductSelection exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/product-selections/key={key}
Checks if a ProductSelection exists with the provided key. Returns a 200 OK status if the ProductSelection exists or a 404 Not Found otherwise.
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.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/product-selections/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if ProductSelection exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/product-selections
Checks if one or more ProductSelections exist for the provided query predicate. Returns a 200 OK status if any ProductSelections match the query predicate, or a 404 Not Found otherwise.
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.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/product-selections -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Create ProductSelection

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:ProductSelectionDraftasapplication/json
Response:
201

ProductSelection

asapplication/json
Request Example:cURL
curl 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
201 Response Example: ProductSelectionjson
{
  "mode": "Individual",
  "id": "dbd58c4a-7b2c-4b45-8134-c95bfd322d05",
  "version": 1,
  "createdAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "key": "finest-selection",
  "name": {
    "en": "Finest Selection"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
    },
    "fields": {
      "description": "my description"
    }
  },
  "productCount": 909
}

Update ProductSelection

Update ProductSelection 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:
application/json
version​
Int​
actions​
Array of ProductSelectionUpdateAction​
Response:
200

ProductSelection

asapplication/json
Request Example:cURL
curl 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
200 Response Example: ProductSelectionjson
{
  "mode": "Individual",
  "id": "dbd58c4a-7b2c-4b45-8134-c95bfd322d05",
  "version": 1,
  "createdAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "key": "finest-selection",
  "name": {
    "en": "Finest Selection"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
    },
    "fields": {
      "description": "my description"
    }
  },
  "productCount": 909
}

Update ProductSelection 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:
application/json
version​
Int​
actions​
Array of ProductSelectionUpdateAction​
Response:
200

ProductSelection

asapplication/json
Request Example:cURL
curl 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
200 Response Example: ProductSelectionjson
{
  "mode": "Individual",
  "id": "dbd58c4a-7b2c-4b45-8134-c95bfd322d05",
  "version": 1,
  "createdAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "key": "finest-selection",
  "name": {
    "en": "Finest Selection"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
    },
    "fields": {
      "description": "my description"
    }
  },
  "productCount": 909
}

Update actions

Add Product

This action is available only for Product Selections with Individual ProductSelectionMode.

Adds a Product to the Product Selection.

If the specified Product is already assigned to the Product Selection, but the existing Product Selection has a different Product Variant Selection, a ProductPresentWithDifferentVariantSelection error is returned.
action​
String​
"addProduct"
product​
ProductResourceIdentifier​

ResourceIdentifier of the Product

variantSelection​
ProductVariantSelection​

Defines which Variants of the Product will be included in the Product Selection. If not supplied all Variants are deemed to be included.

Example: json
{
  "action": "addProduct",
  "product": {
    "typeId": "product",
    "key": "millennium-falcon"
  },
  "variantSelection": {
    "type": "includeOnly",
    "skus": [
      "metallic-white"
    ]
  }
}

Exclude Product

This action is available only for Product Selections with IndividualExclusion ProductSelectionMode.
Excludes a Product from a Product Selection with IndividualExclusion ProductSelectionMode.
If the specified Product is already assigned to the Product Selection, but the existing Product Selection has a different Product Variant Exclusion, a ProductPresentWithDifferentVariantSelection error is returned.
action​
String​
"excludeProduct"
product​
ProductResourceIdentifier​

ResourceIdentifier of the Product

variantExclusion​
ProductVariantExclusion​

Defines which Variants of the Product will be excluded from the Product Selection. If not supplied all Variants are deemed to be excluded.

Example: json
{
  "action": "excludeProduct",
  "product": {
    "typeId": "product",
    "key": "millennium-falcon"
  },
  "variantExclusion": {
    "skus": [
      "metallic-white"
    ]
  }
}

Set Variant Selection

This action is available only for Product Selections with Individual ProductSelectionMode.
Updates the Product Variant Selection of an existing Product Selection Assignment. A ProductVariantSelection can only be set if the Product has already been included in the Product Selection with Individual ProductSelectionMode.
If the specified Product is not assigned to the Product Selection, a ProductAssignmentMissing error is returned.
action​
String​
"setVariantSelection"
product​
ProductResourceIdentifier​

ResourceIdentifier of the Product

variantSelection​
ProductVariantSelection​

Determines which Variants of the previously added Product are to be included in, or excluded from, the Product Selection. Leave it empty to unset an existing Variant Selection.

Example: json
{
  "action": "setVariantSelection",
  "product": {
    "typeId": "product",
    "key": "millennium-falcon"
  },
  "variantSelection": {
    "type": "includeOnly",
    "skus": [
      "M0E20000000EH3V"
    ]
  }
}

Set Variant Exclusion

This action is available only for Product Selections with IndividualExclusion ProductSelectionMode.
Updates the Product Variant Exclusion of an existing Product Selection Assignment. A ProductVariantExclusion can only be set if the Product has already been excluded from the Product Selection with IndividualExclusion ProductSelectionMode.
If the specified Product is not assigned to the Product Selection, a ProductAssignmentMissing error is returned.
action​
String​
"setVariantExclusion"
product​
ProductResourceIdentifier​

ResourceIdentifier of the Product

variantExclusion​
ProductVariantExclusion​
Determines which Variants of the previously excluded Product are to be included in the Product Selection with IndividualExclusion ProductSelectionMode. Leave it empty to unset an existing Variant Exclusion.
Example: json
{
  "action": "setVariantExclusion",
  "product": {
    "typeId": "product",
    "key": "millennium-falcon"
  },
  "variantExclusion": {
    "skus": [
      "M0E20000000EH3V",
      "M0E20000000EH4Q",
      "M0E20000000EH5J"
    ]
  }
}

Remove Product

action​
String​
"removeProduct"
product​
ProductResourceIdentifier​

ResourceIdentifier of the Product

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

Set Key

action​
String​
"setKey"
key​
String​
If key is absent or null, the existing key, if any, will be removed.
Example: json
{
  "action": "setKey",
  "key": "ProductSelectionKey"
}

Change Name

action​
String​
"changeName"
name​
LocalizedString​

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​
TypeResourceIdentifier​
Defines the Type that extends the ProductSelection with Custom Fields. If absent, any existing Type and Custom Fields are removed from the ProductSelection.
fields​
FieldContainer​
Sets the Custom Fields fields for the ProductSelection.
Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set CustomField

action​
String​
"setCustomField"
name​
String​
Name of the Custom Field.
value​
CustomFieldValue​
If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.
Example: json
{
  "action": "setCustomField",
  "name": "exampleStringField",
  "value": "TextString"
}

Delete ProductSelection

Delete ProductSelection by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/product-selections/{id}
Deletion will only succeed if the Product Selection is not assigned to any Store.
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:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

ProductSelection

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/product-selections/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ProductSelectionjson
{
  "mode": "Individual",
  "id": "dbd58c4a-7b2c-4b45-8134-c95bfd322d05",
  "version": 1,
  "createdAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "key": "finest-selection",
  "name": {
    "en": "Finest Selection"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
    },
    "fields": {
      "description": "my description"
    }
  },
  "productCount": 909
}

Delete ProductSelection by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/product-selections/key={key}
Deletion will only succeed if the Product Selection is not assigned to any Store.
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:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

ProductSelection

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/product-selections/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ProductSelectionjson
{
  "mode": "Individual",
  "id": "dbd58c4a-7b2c-4b45-8134-c95bfd322d05",
  "version": 1,
  "createdAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedAt": "2021-06-27T10:12:16.154Z",
  "lastModifiedBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "gqjDgvivRSfJ4fCrk6Lu3j7x",
    "isPlatformClient": false
  },
  "key": "finest-selection",
  "name": {
    "en": "Finest Selection"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
    },
    "fields": {
      "description": "my description"
    }
  },
  "productCount": 909
}