Introduced Product Selections in Beta

25 January 2022

Composable Commerce

HTTP API

New feature

Product catalogProject configurationMessages/SubscriptionsGraphQL

Product Selections let you model the availability of your products in different sales channels. Depending on your use case and by leveraging the existing Stores functionality you can create individual catalogs or assortments for your brand sites, regional shops or brick-and-mortar stores.

Currently, the feature allows you to create Product Selections, populate them with Products, add them to any of your Stores and activate them independently for each Store. We also introduced a new endpoint that returns a Product Projection available in a given Store's active Product Selections.

Please note that the focus of this first release lies in scenarios where assortment management happens in a commercetools-external product information management (PIM) system and a commercetools-external search provider is used for product discovery in the shop frontend. As a consequence, you currently can’t filter your search results by Product Selections or Stores in both, Product Projections and the Merchant Center Product list. We plan to close these gaps progressively and add more functionality to Product Selections during the public beta phase.

Read more on Product Selections and how to use them in the API reference.

Read more on how to integrate with an external search service providing product discovery for your Store-specific shop frontends in this guide.

Furthermore, you can now subscribe to Messages triggered when Product Selections are created, deleted, or updated or when the Store's Product Selections have changed.

Changes:

[API] Added the view_product_selections and manage_product_selections OAuth scopes.
[API] Added ProductSelections.
[API] Added query on Product Selections for a Product.
[API] Added Get ProductProjection in Store by ID or by Key.
[API] Added ProductSelectionCreated and ProductSelectionDeleted Message.
[API] Added ProductSelectionProductAdded and ProductSelectionProductRemoved Message.
[API] Added StoreProductSelectionsChanged Message.
[GraphQL API] Added the following types to the GraphQL schema: AddProductSelectionProduct, AddStoreProductSelection, ChangeProductSelectionName, ChangeStoreProductSelectionActive, CreateProductSelectionDraft, IndividualProductSelectionCreatedPayload, ProductAssignment, ProductAssignmentQueryResult, ProductOfSelection, ProductOfSelectionQueryResult, ProductSelection, ProductSelectionCreated, ProductSelectionCreatedPayload, ProductSelectionDeleted, ProductSelectionProductAdded, ProductSelectionProductRemoved, ProductSelectionQueryInterface, ProductSelectionQueryResult, ProductSelectionSetting, ProductSelectionSettingDraft, ProductSelectionSettingInActionInput, ProductSelectionUpdateAction, RemoveProductSelectionProduct, RemoveStoreProductSelection, SelectionOfProduct, SelectionOfProductQueryResult, SetProductSelectionKey, SetStoreProductSelections, StoreProductSelectionsChanged.
[GraphQL API] Changed the CreateStore type:
- Input field productSelections was added to CreateStore type
[GraphQL API] Changed the Query type:
- Added the productSelections field to the Query type.
- Query.inStores description is changed
- Query object type now implements ProductSelectionQueryInterface interface
- Added the productSelectionAssignments field to the Query type.
- Added the productSelection field to the Query type.
- Query.inStore description is changed
[GraphQL API] Changed the Mutation type:
- Added the updateProductSelection field to the Mutation type.
- Added the deleteProductSelection field to the Mutation type.
- Added the createProductSelection field to the Mutation type.
[GraphQL API] Changed the Product type:
- Added the productSelectionRefs field to the Product type.
[GraphQL API] Changed the StoreCreated type:
- Added the productSelections field to the StoreCreated type.
- Added the productSelectionsRef field to the StoreCreated type.
[GraphQL API] Changed the Store type:
- Added the productSelections field to the Store type.
[GraphQL API] Changed the StoreUpdateAction type:
- Input field changeProductSelectionActive was added to StoreUpdateAction type
- Input field setProductSelections was added to StoreUpdateAction type
- Input field addProductSelection was added to StoreUpdateAction type
- Input field removeProductSelection was added to StoreUpdateAction type
[GraphQL API] Changed the InStore type:
- Added the product field to the InStore type.
- Added the productSelectionAssignments field to the InStore type.

The following changes were introduced in terms of GraphQL SDL:

extend type InStore {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  product(
    "Queries for a product with specified SKU"
    sku: String,

    "Queries for a product with specified [product variant key](https://docs.commercetools.com/api/projects/products#variant_key)"
    variantKey: String,

    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): Product

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  productSelectionAssignments(where: String, sort: [String!], limit: Int, offset: Int): ProductAssignmentQueryResult!
}

extend type Query {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  productSelection(
    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): ProductSelection

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  productSelectionAssignments(where: String, sort: [String!], limit: Int, offset: Int): ProductAssignmentQueryResult!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  productSelections(where: String, sort: [String!], limit: Int, offset: Int): ProductSelectionQueryResult!
}

extend type Mutation {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  createProductSelection(
    "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
    draft: CreateProductSelectionDraft!): ProductSelection

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  deleteProductSelection(version: Long!,

    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): ProductSelection

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  updateProductSelection(version: Long!,

    "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
    actions: [ProductSelectionUpdateAction!]!,

    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): ProductSelection
}

extend type Product {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  productSelectionRefs(where: String, sort: [String!], limit: Int, offset: Int): SelectionOfProductQueryResult!
}

extend type StoreCreated {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  productSelections: [ProductSelectionSetting!]!
}

extend type Store {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  productSelections: [ProductSelectionSetting!]!
}

extend input StoreUpdateAction {
  addProductSelection: AddStoreProductSelection
  changeProductSelectionActive: ChangeStoreProductSelectionActive
  removeProductSelection: RemoveStoreProductSelection
  setProductSelections: SetStoreProductSelections
}

extend input CreateStore {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  productSelections: [ProductSelectionSettingDraft!]
}

input AddProductSelectionProduct {
  product: ResourceIdentifierInput!
}

input AddStoreProductSelection {
  productSelection: ResourceIdentifierInput!
  active: Boolean
}

input ChangeProductSelectionName {
  name: [LocalizedStringItemInputType!]!
}

input ChangeStoreProductSelectionActive {
  productSelection: ResourceIdentifierInput!
  active: Boolean!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input CreateProductSelectionDraft {
  key: String
  name: [LocalizedStringItemInputType!]!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type IndividualProductSelectionCreatedPayload implements ProductSelectionCreatedPayload {
  name(
    "String is defined for different locales. This argument specifies the desired locale."
    locale: Locale,

    "List of languages the client is able to understand, and which locale variant is preferred."
    acceptLanguage: [Locale!]): String
  nameAllLocales: [LocalizedString!]!
  type: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductAssignment {
  productRef: Reference!
  product: Product
  productSelectionRef: Reference!
  productSelection: ProductSelection
}

type ProductAssignmentQueryResult {
  offset: Int!
  count: Int!
  total: Long!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  exists: Boolean!
  results: [ProductAssignment!]!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductOfSelection {
  productRef: Reference!
  product: Product
}

type ProductOfSelectionQueryResult {
  offset: Int!
  count: Int!
  total: Long!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  exists: Boolean!
  results: [ProductOfSelection!]!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductSelection implements Versioned {
  key: String
  name(
    "String is defined for different locales. This argument specifies the desired locale."
    locale: Locale,

    "List of languages the client is able to understand, and which locale variant is preferred."
    acceptLanguage: [Locale!]): String
  nameAllLocales: [LocalizedString!]!
  productRefs(where: String, sort: [String!], limit: Int, offset: Int): ProductOfSelectionQueryResult!
  productCount: Int!
  id: String!
  version: Long!
  createdAt: DateTime!
  lastModifiedAt: DateTime!
  createdBy: Initiator
  lastModifiedBy: Initiator
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductSelectionCreated implements MessagePayload {
  productSelection: ProductSelectionCreatedPayload!
  type: String!
}

interface ProductSelectionCreatedPayload {
  name(
    "String is defined for different locales. This argument specifies the desired locale."
    locale: Locale,

    "List of languages the client is able to understand, and which locale variant is preferred."
    acceptLanguage: [Locale!]): String
  nameAllLocales: [LocalizedString!]!
  type: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductSelectionDeleted implements MessagePayload {
  type: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductSelectionProductAdded implements MessagePayload {
  product: Product
  productRef: Reference!
  type: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductSelectionProductRemoved implements MessagePayload {
  product: Product
  productRef: Reference!
  type: String!
}

"Fields to access product selection assignments. BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
interface ProductSelectionQueryInterface {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  productSelectionAssignments(where: String, sort: [String!], limit: Int, offset: Int): ProductAssignmentQueryResult!
}

type ProductSelectionQueryResult {
  offset: Int!
  count: Int!
  total: Long!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  exists: Boolean!
  results: [ProductSelection!]!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductSelectionSetting {
  productSelectionRef: Reference!
  productSelection: ProductSelection
  active: Boolean!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ProductSelectionSettingDraft {
  productSelection: ResourceIdentifierInput!
  active: Boolean!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ProductSelectionSettingInActionInput {
  productSelection: ResourceIdentifierInput!
  active: Boolean
}

input ProductSelectionUpdateAction {
  addProduct: AddProductSelectionProduct
  changeName: ChangeProductSelectionName
  removeProduct: RemoveProductSelectionProduct
  setKey: SetProductSelectionKey
}

input RemoveProductSelectionProduct {
  product: ResourceIdentifierInput!
}

input RemoveStoreProductSelection {
  productSelection: ResourceIdentifierInput!
}

type SelectionOfProduct {
  productSelectionRef: Reference!
  productSelection: ProductSelection
}

type SelectionOfProductQueryResult {
  offset: Int!
  count: Int!
  total: Long!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  exists: Boolean!
  results: [SelectionOfProduct!]!
}

input SetProductSelectionKey {
  key: String
}

input SetStoreProductSelections {
  productSelections: [ProductSelectionSettingInActionInput!]
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type StoreProductSelectionsChanged implements MessagePayload {
  addedProductSelections: [ProductSelectionSetting!]
  removedProductSelections: [ProductSelectionSetting!]
  updatedProductSelections: [ProductSelectionSetting!]
  type: String!
}