Documentation

Model assortments with Product Selections

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

Learn how to use Product Selections to model different assortments sold in specific world regions.

Learning goal

This tutorial teaches you how to model product assortments in Composable Commerce. Based on a global product catalog, we will set up region-specific assortments and demonstrate that these products are only available in the store specific to the region. You will learn how to make parts of your product catalog available on your storefront for different market segments. This tutorial also shows you how to exclude specific products from your catalog in case you need to remove them due to, for example, a recall or defect.

Prerequisites

To follow this tutorial, we assume that you:

Preparation

For this tutorial, we use the B2C Retail Store example data set, which provides us with a couple of products from our default catalog. This example data set contains home decor and furniture products that we will split into different assortments. Let's say we decide not to sell furniture everywhere in the world because we can't ship those bulky goods worldwide for a reasonable price. Given that we are based in Europe, we sell the furniture only in regions covering Europe.
In our example scenario, we'll have assortments tailored for mainland Europe (EU), the United Kingdom (UK), and the United States (US). We will create Product Selections for the different region-specific assortments and assign specific products to the Product Selections. To control the availability of our assortments on the respective storefronts, we need to associate the Product Selection with region-specific Stores, the EU Store, the UK Store, and the US Store. With Store-scoped API calls, we then demonstrate that specific products are only available in specific regions.

Add Product Selections

Let's begin with modeling the assortment for the US Store. As said before, we don't want to offer furniture in the US, so we allocate to the Product Selection Assortment US only those Products that do not belong to the furniture Category or its subcategories.
Let's add the Product Selection Assortment US of type Inclusion in the Merchant Center.
Add Product Selection for Assortment US

We now have created the Product Selection, but it does not yet have any Products assigned.

Product Selection created
Before we assign Products to the Product Selection, we create the Product Selections Assortment EU and Assortment UK in the same way.

Add Products to Product Selections

Assortment US

We will use the Bulk-assign Products to a Product Selection feature in the Merchant Center to assign to the Assortment US all Products that do not belong to the Category furniture or any of its subcategories. Set the filter in the Products list as shown in the following image, and you'll see that 75 Products match our filter. If you then select the checkbox in the column header of the Product list, you'll notice that only 20 Products are selected by default. To select all 75 Products simultaneously, change the Items per page selector at the bottom of the Product list to 100.
If you need to apply a bulk action to more than 100 Products, then you must apply the action in multiple steps. This is because you can select a maximum of 100 Products for a bulk action.
From the Actions drop-down, select and perform the Bulk-assign products to a product selection action.
Filter for non-furniture products
Select Assortment US from the list of Product Selections and assign All variants of the selected Products.
Assign Products with all variants

Assortment EU

Now we will add almost everything from the default catalog (including furniture) to Assortment EU. The only difference between these two assortments will be the availability of the Product Nala Two-Seater Sofa. In our default catalog, this Product is available in seven colors. Our statistics show that this sofa does not sell well in mainland Europe in the colors Royal Blue and Steel Gray. Instead, the colors Peacock Blue and Feather Gray are very popular in the UK, but the other two colors do not sell well. We will address this by adding only the popular Variants of this Product to the region-specific assortments.
Variant IDSKUColor labelAssortment
1NTSS-01Steel GrayUK
2NTSS-02Royal BlueUK
3NTSS-03TerracottaEU & UK
4NTSS-04Peacock BlueEU
5NTSS-05Feather GrayEU
6NTSS-06Stage GreenEU and UK
7NTSS-07CharcoalEU and UK
We use the Bulk-assign Products to a Product Selection Merchant Center feature again, but this time we don't use any filters on the Product list. Since we want to exclude two colors of the Nala Two-Seater Sofa from the Assortment EU, we use a filter on the variants for this Product. Instead of All variants, we pick the SKUs NTSS-01 and NTSS-01 from the list of variants for this Product as exceptions:
Add product except SKUs NTSS-01 and NTSS-02

Assortment UK

For Assortment UK we do almost the same as before, the only difference is that we pick the SKUs NTSS-04 and NTSS-05 from the list of variants for Nala Two-Seater Sofa as exceptions.

We have now prepared the assortments for the different countries, but we need to make sure that they are only available in those countries. To do this, we will use Stores.

Add Stores

The example data set is preconfigured with the B2C Retail Store that we can use as the default Store offering the entire product catalog. We now add the region-specific EU Store, Germany Store, BeNeLux Store, UK Store, and US Store with the Merchant Center as described in the documentation.

Use following settings when creating the Stores:

Store keyStore nameCountryProduct Selection
eu-storeEU StoreEuropean Union (EU)Assortment EU
germany-storeGermany StoreGermanyAssortment EU
benelux-storeBeNeLux StoreBelgium, Netherlands, LuxembourgAssortment EU
uk-storeUK StoreUnited Kingdom (UK)Assortment UK
us-storeUS StoreUnited States (US)Assortment US
Leave settings for Inventory supply channels, Product distribution channels, and Languages empty for each Store.
Activate the Product Selection before you click Create store.
Activate Product Selection for Store

Now that we have assigned our assortments to the different Stores, we can check if the Products are only available in the assigned Store.

Check availability in Store

Let's simulate that we offer the region-specific assortments on their own storefronts, hosted in the region where we sell our Products. In addition, we provide another storefront for the rest of the world, that offers the entire product catalog. Since each storefront runs independently, we let them connect to our Composable Commerce Project through their individual API Clients. This results in the creation of four API Clients, each of them scoped to their Store.

Create Store-scoped API Clients

We create read-only API Clients for each of our Stores as described in the Merchant Center documentation and save the client credentials as Postman or Bruno environment files.

Retrieve Products in global Store

Load the environment for the B2C Retail Store API Client in Postman or Bruno and obtain an access token.
We use the Store-scoped Get ProductProjection in Store by Key endpoint to simulate a request from our global storefront.
You can find this endpoint in the In-store folder of the Postman collection:
In-store folder in Postman collection
For this request we need to get the Product key for the Product Nala Two-Seater Sofa from the Merchant Center, that is nala-two-seater-sofa.
For the global Store with key b2c-retail-store, this API request returns all of the variants for this Product:
GET /{projectKey}/in-store/key=b2c-retail-store/product-projections/key=nala-two-seater-sofa
{
  "masterVariant": {
    "id": 1,
    "sku": "NTSS-01"
  },
  "variants": [
    {
      "id": 2,
      "sku": "NTSS-02"
    },
    {
      "id": 3,
      "sku": "NTSS-03"
    },
    {
      "id": 4,
      "sku": "NTTS-04"
    },
    {
      "id": 5,
      "sku": "NTSS-05"
    },
    {
      "id": 6,
      "sku": "NTSS-06"
    },
    {
      "id": 7,
      "sku": "NTSS-07"
    }
  ],
  "key": "nala-two-seater-sofa"
}

We have shortened the JSON examples for the API responses to focus on the fields that are essential for the course of this tutorial.

Retrieve Products in Germany Store

The same request, but for the Germany Store returns the Product with only the five SKUs we want to offer in the EU.

GET /{projectKey}/in-store/key=germany-store/product-projections/key=nala-two-seater-sofa
{
  "masterVariant": {
    "id": 3,
    "sku": "NTSS-03"
  },
  "variants": [
    {
      "id": 4,
      "sku": "NTTS-04"
    },
    {
      "id": 5,
      "sku": "NTSS-05"
    },
    {
      "id": 6,
      "sku": "NTSS-06"
    },
    {
      "id": 7,
      "sku": "NTSS-07"
    }
  ],
  "key": "nala-two-seater-sofa"
}

Retrieve Products in UK Store

The same request but for the UK Store returns the Product without the SKUs NTSS-04 and NTSS-05 that we want to hide from the UK market.
GET /{projectKey}/in-store/key=uk-store/product-projections/key=nala-two-seater-sofa
{
  "masterVariant": {
    "id": 1,
    "sku": "NTSS-01"
  },
  "variants": [
    {
      "id": 2,
      "sku": "NTSS-02"
    },
    {
      "id": 3,
      "sku": "NTSS-03"
    },
    {
      "id": 6,
      "sku": "NTSS-06"
    },
    {
      "id": 7,
      "sku": "NTSS-07"
    }
  ],
  "key": "nala-two-seater-sofa"
}

Retrieve Products in US Store

As expected, the same request but for the US Store does not return the Product.

GET /{projectKey}/in-store/key=us-store/product-projections/key=nala-two-seater-sofa
{
  "statusCode": 404,
  "message": "The Resource with key 'nala-two-seater-sofa' was not found.",
  "errors": [
    {
      "code": "ResourceNotFound",
      "message": "The Resource with key 'nala-two-seater-sofa' was not found."
    }
  ]
}

Exclude Products from Product Selections

For the next scenario, we will use the Product Search API, which is designed for product discovery in store fronts. If we search for "rug" in our global B2C Retail Store, we can currently find all the eight rugs we have in our catalog.
Search request: POST /{projectKey}/products/searchjson
{
  "query": {
    "and": [
      {
        "fullText": {
          "field": "name",
          "language": "en-US",
          "value": "rug"
        }
      },
      {
        "exact": {
          "field": "stores",
          "value": "{{ ID of B2C Retail Store }}"
        }
      }
    ]
  }
}
Search responsejson
{
  "total": 8,
  "offset": 0,
  "limit": 20,
  "facets": [],
  "results": [
    // eight Product IDs.
  ]
}

Let's say that due to difficulties with one of our suppliers, we are not sure when we will be able to offer rugs again and need to temporarily remove these eight products from the catalog.

Create Product Selection

To do this, we create a Product Selection of type Exclusion, to which we explicitly add the Products we want to exclude from the assortment. We follow the same steps as in Add Product Selections, but this time we choose Product Selection Type Exclusion for our Excluded Rugs.
We then add all rugs to this Product Selection, similar to Add Products to Product Selections, but this time we filter for the Category Rugs. We add All variants to the Product Selection and save.
Finally, assign the Product Selection to the B2C Retail Store and activate it as described in Add Stores.

Check availability in Stores

We now try the search request from before and see that it does not return any products this time.

Search responsejson
{
  "total": 0,
  "offset": 0,
  "limit": 20,
  "facets": [],
  "results": []
}

If we try the search request for the UK Store instead, we see that the Products can still be found.

Search request: POST /{projectKey}/products/searchjson
{
  "query": {
    "and": [
      {
        "fullText": {
          "field": "name",
          "language": "en-US",
          "value": "rug"
        }
      },
      {
        "exact": {
          "field": "stores",
          "value": "{{ ID of UK Store }}"
        }
      }
    ]
  }
}
Search responsejson
{
  "total": 8,
  "offset": 0,
  "limit": 20,
  "facets": [],
  "results": [
    // eight Product IDs.
  ]
}
To make the Products unavailable for all regions, we need to assign the Excluded Rugs Product Selection to all of our Stores.

Summary

In this tutorial, you have learned how to use Product Selections and Stores to model assortments that you want to make available on your storefronts. You also have learned that you use Stores for your region-specific assortments, which you can access through their Store-specific API clients. You have learned how to include specific Product Variants in an assortment and how to temporarily exclude entire Products from the assortment . You know how to retrieve the Products in a Store using the Product Projection API and the Product Search API.