VariantRequestSettings

VariantRequestSettings controls whether Product Search and Product Recommendation requests return Product-only results, one selected Variant per Product, or multiple Variants per Product.

Use VariantRequestSettings instead of the older Search setting ExplodedVariants and the older Recommendation setting RecommendVariant. The legacy settings are obsolete and only remain for backwards compatibility.

Settings

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

MaxVariantsPerProduct

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

For Product Search requests, MaxVariantsPerProduct replaces the obsolete ExplodedVariants setting.

For Product Recommendation requests, MaxVariantsPerProduct = 1 replaces the common legacy behavior of RecommendVariant = true, while MaxVariantsPerProduct = 0 replaces RecommendVariant = false.

Sorting

Value	Behavior	Recommended for
GroupedByProduct	Keeps Product ranking dominant and returns Variants grouped under their Product.	Product listing pages and classic Product-focused result lists.
ByRelevance	Allows concrete Variants to participate more directly in relevance ranking.	Variant-focused Search and Recommendation experiences where the exact Variant matters.

GroupedByProduct is usually the safer first choice for Product listing pages. Use ByRelevance when the experience should surface the most relevant concrete Variants, even if that means several Variants from one Product can rank close to Variants from other Products.

Recommended Starting Points

Experience	Suggested setting
Product-only result list	MaxVariantsPerProduct = 0
Product result with one selected Variant	MaxVariantsPerProduct = 1
Product listing page with a few visible Variants	MaxVariantsPerProduct = 2 to 5, Sorting = GroupedByProduct
Variant-focused Search or Recommendation experience	MaxVariantsPerProduct = 2 to 5, Sorting = ByRelevance

Search Examples

The examples below configure a Product Search request to return up to five Variants per Product and let those Variants participate in relevance-based ordering.

JSON

{
  "$type": "Relewise.Client.Requests.Search.ProductSearchRequest, Relewise.Client",
  "Term": "red helmet",
  "Settings": {
    "VariantRequestSettings": {
      "MaxVariantsPerProduct": 5,
      "Sorting": "ByRelevance"
    }
  },
  "Skip": 0,
  "Take": 20,
  "Language": {
    "Value": "en-US"
  },
  "Currency": {
    "Value": "EUR"
  }
}

.NET

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

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

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("red helmet")
  .setVariantRequestSettings((variantSettings) => {
    variantSettings.setMaxVariantsPerProduct(5);
    variantSettings.setSorting("ByRelevance");
  })
  .pagination((pagination) => {
    pagination.setPageSize(20);
    pagination.setPage(1);
  })
  .build();

const response = await searcher.searchProducts(request);

Recommendation Examples

The examples below configure a Purchased With Product recommendation to return up to three Variants per Product and rank concrete Variants by relevance.

JSON

{
  "$type": "Relewise.Client.Requests.Recommendations.PurchasedWithProductRequest, Relewise.Client",
  "ProductAndVariantId": {
    "ProductId": "skate-helmet",
    "VariantId": "red-medium"
  },
  "Settings": {
    "NumberOfRecommendations": 12,
    "AllowFillIfNecessaryToReachNumberOfRecommendations": true,
    "VariantRequestSettings": {
      "MaxVariantsPerProduct": 3,
      "Sorting": "ByRelevance"
    }
  },
  "Language": {
    "Value": "en-US"
  },
  "Currency": {
    "Value": "EUR"
  }
}

.NET

using Relewise.Client.DataTypes;
using Relewise.Client.Requests.Recommendations;
using Relewise.Client.Requests.Shared;

PurchasedWithProductRequest request = new(
    language: new Language("en-US"),
    currency: new Currency("EUR"),
    displayedAtLocationType: "PDP - Purchased With",
    user: User.ByTemporaryId("user-123"),
    productAndVariantId: new ProductAndVariantId("skate-helmet", "red-medium"))
{
    Settings = new ProductRecommendationRequestSettings
    {
        NumberOfRecommendations = 12,
        AllowFillIfNecessaryToReachNumberOfRecommendations = true,
        VariantRequestSettings = new VariantRecommendationRequestSettings
        {
            MaxVariantsPerProduct = 3,
            Sorting = VariantSorting.ByRelevance,
        },
    },
};

TS/JS

import { PurchasedWithProductBuilder, Recommender, UserFactory } from "@relewise/client";

const recommender = new Recommender(RELEWISE_DATASET_ID, RELEWISE_API_KEY, {
  serverUrl: RELEWISE_SERVER_URL,
});

const request = new PurchasedWithProductBuilder({
  language: "en-US",
  currency: "EUR",
  displayedAtLocation: "PDP - Purchased With",
  user: UserFactory.byTemporaryId("user-123"),
})
  .product({
    productId: "skate-helmet",
    variantId: "red-medium",
  })
  .setNumberOfRecommendations(12)
  .allowFillIfNecessaryToReachNumberOfRecommendations(true)
  .setVariantRequestSettings((variantSettings) => {
    variantSettings.setMaxVariantsPerProduct(3);
    variantSettings.setSorting("ByRelevance");
  })
  .build();

const response = await recommender.recommendPurchasedWithProduct(request);