VariantRequestSettings in Search

ProductSearchSettings.VariantRequestSettings controls how many Variants a Product Search request may return per Product and how those Variants are ordered.

Use VariantRequestSettings when the storefront displays concrete Variants in Search results, such as individual colors, sizes, materials, dimensions, or configurations.

For Product Recommendation requests, see VariantRequestSettings in Recommendations.

Legacy setting

ExplodedVariants is obsolete. Use VariantRequestSettings.MaxVariantsPerProduct instead.

If both settings are present, VariantRequestSettings takes precedence.

Settings

Setting	Description
MaxVariantsPerProduct	The maximum number of Variants that may be returned for each Product.
Sorting	Defines whether Variants remain grouped by Product or are ordered by their own relevance.

MaxVariantsPerProduct

Value	Behavior
0	Return Product-only results.
1	Return one selected Variant per Product.
2+	Allow multiple Variants per Product.

Keep this value close to the number of Variants the storefront can display. For Product listing pages, a value between 1 and 5 is usually a practical starting point.

Sorting

Value	Behavior	Use when
GroupedByProduct	Keeps Product ranking dominant and returns Variants together under their Product.	The storefront presents a Product-first result list.
ByRelevance	Allows concrete Variants to be ordered by Variant-level relevance.	The exact Variant matters and Variants may be mixed according to relevance.

GroupedByProduct is the default and preserves the existing Product-first behavior unless ByRelevance is selected explicitly.

Use ByRelevance to let Relewise consider signals such as Variant popularity, the current User's context, and relations between Variants that users view, add to cart, or purchase together.

For personalized Variant-to-Variant relevance, track interactions with the relevant Variant IDs and use the same User when tracking behavior and making the Search request.

Implementation Considerations

When trying the Variant-level experience, start with MaxVariantsPerProduct between 2 and 4 and compare both sorting modes. Use ByRelevance when the storefront presents Variants similarly to individual Products.

Before returning multiple Variants, ensure that the storefront can:

• Display the same Product more than once with different Variants.
• Use each returned Variant's images, prices, links, and add-to-cart details.
• Track concrete Variant IDs in Product views, carts, and orders.

If behavioral tracking includes only Product IDs, Relewise has limited Variant-level signals for personalization and Variant-to-Variant relevance. Test the result presentation carefully, because multiple Variants can improve choice for some catalogs but feel repetitive for others.

Term-Based Search Example

Suppose a user adds a red shirt Variant to the cart and then searches for shoes. With Sorting = ByRelevance, Relewise can prioritize shoe Variants related to that exact shirt Variant instead of selecting each shoe Product's globally most popular Variant.

The cart behavior is not part of the Search request below. It must already have been tracked for the same User.

This example returns up to five Variants per Product and allows the concrete Variants to be ordered by relevance.

JSON

{
  "$type": "Relewise.Client.Requests.Search.ProductSearchRequest, Relewise.Client",
  "Language": {
    "Value": "en-US"
  },
  "Currency": {
    "Value": "EUR"
  },
  "DisplayedAtLocation": "Search Page",
  "User": {
    "TemporaryId": "user-123"
  },
  "Term": "shoes",
  "Skip": 0,
  "Take": 20,
  "Settings": {
    "VariantRequestSettings": {
      "MaxVariantsPerProduct": 5,
      "Sorting": "ByRelevance"
    }
  }
}

.NET

using Relewise.Client.DataTypes;
using Relewise.Client.Requests.Search;
using Relewise.Client.Requests.Search.Settings;
using Relewise.Client.Requests.Shared;
using Relewise.Client.Responses.Search;

ProductSearchRequest request = new(
    language: new Language("en-US"),
    currency: new Currency("EUR"),
    user: User.ByTemporaryId("user-123"),
    displayedAtLocation: "Search Page",
    term: "shoes",
    skip: 0,
    take: 20)
{
    Settings = new ProductSearchSettings
    {
        VariantRequestSettings = new VariantSearchRequestSettings
        {
            MaxVariantsPerProduct = 5,
            Sorting = VariantSorting.ByRelevance,
        },
    },
};

ProductSearchResponse response = await searcher.SearchAsync(request);

TS/JS

import { ProductSearchBuilder, Searcher, UserFactory } from "@relewise/client";

const searcher = new Searcher(RELEWISE_DATASET_ID, RELEWISE_API_KEY, {
  serverUrl: RELEWISE_SERVER_URL,
});

const request = new ProductSearchBuilder({
  language: "en-US",
  currency: "EUR",
  displayedAtLocation: "Search Page",
  user: UserFactory.byTemporaryId("user-123"),
})
  .setTerm("shoes")
  .setVariantRequestSettings((variantSettings) => {
    variantSettings.setMaxVariantsPerProduct(5);
    variantSettings.setSorting("ByRelevance");
  })
  .pagination((pagination) => {
    pagination.setPageSize(20);
    pagination.setPage(1);
  })
  .build();

const response = await searcher.searchProducts(request);

Product Listing Page Example

On a termless Product listing page, ByRelevance prevents all Variants of a popular Product from being forced into one group ahead of more relevant Variants from other Products. Each returned Variant can instead take its position according to its own relevance in the current context.

This example creates a termless Search for the party-supplies Product Category. It returns up to five Variants per Product and lets Variant popularity and relevance influence their order.

JSON

{
  "$type": "Relewise.Client.Requests.Search.ProductSearchRequest, Relewise.Client",
  "Language": {
    "Value": "en-US"
  },
  "Currency": {
    "Value": "EUR"
  },
  "DisplayedAtLocation": "Category Page",
  "User": {
    "TemporaryId": "user-123"
  },
  "Term": null,
  "Skip": 0,
  "Take": 20,
  "Filters": {
    "Items": [
      {
        "$type": "Relewise.Client.Requests.Filters.ProductCategoryIdFilter, Relewise.Client",
        "CategoryIds": ["party-supplies"],
        "EvaluationScope": "Ancestor",
        "Negated": false
      }
    ]
  },
  "Settings": {
    "VariantRequestSettings": {
      "MaxVariantsPerProduct": 5,
      "Sorting": "ByRelevance"
    }
  }
}

.NET

using Relewise.Client.DataTypes;
using Relewise.Client.Requests.Filters;
using Relewise.Client.Requests.Search;
using Relewise.Client.Requests.Search.Settings;
using Relewise.Client.Requests.Shared;
using Relewise.Client.Responses.Search;

ProductSearchRequest request = new(
    language: new Language("en-US"),
    currency: new Currency("EUR"),
    user: User.ByTemporaryId("user-123"),
    displayedAtLocation: "Category Page",
    term: null,
    skip: 0,
    take: 20)
{
    Filters = new FilterCollection(new ProductCategoryIdFilter(
        categoryId: "party-supplies",
        evaluationScope: CategoryScope.Ancestor)),
    Settings = new ProductSearchSettings
    {
        VariantRequestSettings = new VariantSearchRequestSettings
        {
            MaxVariantsPerProduct = 5,
            Sorting = VariantSorting.ByRelevance,
        },
    },
};

ProductSearchResponse response = await searcher.SearchAsync(request);

TS/JS

import { ProductSearchBuilder, Searcher, UserFactory } from "@relewise/client";

const searcher = new Searcher(RELEWISE_DATASET_ID, RELEWISE_API_KEY, {
  serverUrl: RELEWISE_SERVER_URL,
});

const request = new ProductSearchBuilder({
  language: "en-US",
  currency: "EUR",
  displayedAtLocation: "Category Page",
  user: UserFactory.byTemporaryId("user-123"),
})
  .setTerm(null)
  .filters((filters) => {
    filters.addProductCategoryIdFilter("Ancestor", "party-supplies");
  })
  .setVariantRequestSettings((variantSettings) => {
    variantSettings.setMaxVariantsPerProduct(5);
    variantSettings.setSorting("ByRelevance");
  })
  .pagination((pagination) => {
    pagination.setPageSize(20);
    pagination.setPage(1);
  })
  .build();

const response = await searcher.searchProducts(request);

For a Product-first listing where all returned Variants of a Product must stay together, keep the same MaxVariantsPerProduct and change Sorting to GroupedByProduct.