VariantRequestSettings in Recommendations

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

Use it when a recommendation placement needs to return concrete Variants, such as the color, size, material, dimension, or configuration that best fits the current User context.

For Product Search requests, see VariantRequestSettings in Search.

Legacy setting

RecommendVariant is obsolete. Use VariantRequestSettings.MaxVariantsPerProduct instead.

• RecommendVariant = true corresponds to MaxVariantsPerProduct = 1.
• RecommendVariant = false corresponds to MaxVariantsPerProduct = 0.

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 recommendations.
1	Return one selected Variant per Product.
2+	Allow multiple Variants per Product for supported Recommendation types.

Multi-Variant recommendations with MaxVariantsPerProduct greater than 1 are currently supported only for:

• PersonalProductRecommendationRequest
• PopularProductsRequest

Support for additional Product Recommendation types will be added later.

For the supported Recommendation types, multiple Variants from the same Product may occupy recommendation positions when they are relevant enough. Keep MaxVariantsPerProduct close to the number of Variants the placement can display.

Sorting

Value	Behavior	Use when
GroupedByProduct	Keeps Variants grouped under their Product.	The placement should remain Product-first.
ByRelevance	Prioritizes concrete Variants using Variant-level relevance.	The recommended Product is useful only when the selected Variant also fits the context.

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

Product selection still follows the chosen Recommendation type. ByRelevance improves which concrete Variants are selected and how multiple returned Variants are ordered.

Variant-to-Variant relevance with ByRelevance is currently supported for the same two Recommendation types:

• PersonalProductRecommendationRequest
• PopularProductsRequest

For personalized Variant-to-Variant relevance, track interactions with the relevant Variant IDs and use the same User when tracking behavior and making the Recommendation 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 placement 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.

Selecting the Most Relevant Variant

Variant-to-Variant relations help Relewise select the right Variant of a recommended Product. For example, if users commonly purchase black shoes, cream scarves, and black bags with a red dress Variant, Relewise can prioritize those concrete Variants instead of the globally most popular Variants of those Products.

This also applies outside fashion. A recommendation can, for example, prioritize the screw length commonly purchased with a particular drywall thickness or the most relevant print of a T-shirt for an outfit.

Returning Multiple Variants of a Product

For Personal and Popular Product Recommendations, set MaxVariantsPerProduct above 1 when more than one Variant of the same Product may be useful in the placement. With Sorting = ByRelevance, Relewise may return two Variants of one Product ahead of another Product when both Variants are more relevant.

For example, a knitting kit placement can recommend several colors of the same yarn Product when those colors are the strongest matches for the kit or the User's interests.

Personal Product Recommendation Example

A Personal Product Recommendation uses the User's context and previous behavior to select both relevant Products and the most relevant concrete Variants. The example returns 12 recommendation positions, allows up to three Variants per Product, and orders those Variants by relevance.

JSON

{
  "$type": "Relewise.Client.Requests.Recommendations.PersonalProductRecommendationRequest, Relewise.Client",
  "Language": {
    "Value": "en-US"
  },
  "Currency": {
    "Value": "EUR"
  },
  "DisplayedAtLocationType": "Front Page",
  "User": {
    "TemporaryId": "user-123"
  },
  "Settings": {
    "NumberOfRecommendations": 12,
    "VariantRequestSettings": {
      "MaxVariantsPerProduct": 3,
      "Sorting": "ByRelevance"
    }
  }
}

.NET

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

PersonalProductRecommendationRequest request = new(
    language: new Language("en-US"),
    currency: new Currency("EUR"),
    displayedAtLocationType: "Front Page",
    user: User.ByTemporaryId("user-123"))
{
    Settings = new ProductRecommendationRequestSettings
    {
        NumberOfRecommendations = 12,
        VariantRequestSettings = new VariantRecommendationRequestSettings
        {
            MaxVariantsPerProduct = 3,
            Sorting = VariantSorting.ByRelevance,
        },
    },
};

ProductRecommendationResponse response = await recommender.RecommendAsync(request);

TS/JS

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

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

const request = new PersonalProductRecommendationBuilder({
  language: "en-US",
  currency: "EUR",
  displayedAtLocation: "Front Page",
  user: UserFactory.byTemporaryId("user-123"),
})
  .setNumberOfRecommendations(12)
  .setVariantRequestSettings((variantSettings) => {
    variantSettings.setMaxVariantsPerProduct(3);
    variantSettings.setSorting("ByRelevance");
  })
  .build();

const response = await recommender.recommendPersonalProducts(request);

Popular Products Recommendation Example

A Popular Products Recommendation still selects Products using the configured popularity period and metric. With Sorting = ByRelevance, Relewise can then prioritize concrete Variants related to the current User's Variant-level interests.

This example recommends Products based on purchases from the last 30 days and allows up to three relevant Variants per Product.

JSON

{
  "$type": "Relewise.Client.Requests.Recommendations.PopularProductsRequest, Relewise.Client",
  "Language": {
    "Value": "en-US"
  },
  "Currency": {
    "Value": "EUR"
  },
  "DisplayedAtLocationType": "Front Page",
  "User": {
    "TemporaryId": "user-123"
  },
  "BasedOn": "MostPurchased",
  "SinceMinutesAgo": 43200,
  "Settings": {
    "NumberOfRecommendations": 12,
    "VariantRequestSettings": {
      "MaxVariantsPerProduct": 3,
      "Sorting": "ByRelevance"
    }
  }
}

.NET

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

PopularProductsRequest request = new(
    language: new Language("en-US"),
    currency: new Currency("EUR"),
    displayedAtLocationType: "Front Page",
    user: User.ByTemporaryId("user-123"),
    basedOn: PopularityTypes.MostPurchased,
    since: TimeSpan.FromDays(30))
{
    Settings = new ProductRecommendationRequestSettings
    {
        NumberOfRecommendations = 12,
        VariantRequestSettings = new VariantRecommendationRequestSettings
        {
            MaxVariantsPerProduct = 3,
            Sorting = VariantSorting.ByRelevance,
        },
    },
};

ProductRecommendationResponse response = await recommender.RecommendAsync(request);

TS/JS

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

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

const request = new PopularProductsBuilder({
  language: "en-US",
  currency: "EUR",
  displayedAtLocation: "Front Page",
  user: UserFactory.byTemporaryId("user-123"),
})
  .basedOn("MostPurchased")
  .sinceMinutesAgo(30 * 24 * 60)
  .setNumberOfRecommendations(12)
  .setVariantRequestSettings((variantSettings) => {
    variantSettings.setMaxVariantsPerProduct(3);
    variantSettings.setSorting("ByRelevance");
  })
  .build();

const response = await recommender.recommendPopularProducts(request);