Storefront API: What is the purpose of the boost field on productList, priceList, category on productSearch?

Questions
1

In the storefront API, on productSearch, it is possible to add a category, product list or price list to limit the search result. All three of these seems to do a “hard” filtering, so that products that do not match the criteria are excluded from the search result.

These three all have a boost field, which i fail to understand the purpose of. Since all hits are required to meet match the criteria, what difference could the boost make? I have tried some simple queries in Nitro but can’t find a case where the boost on these matters. Any case that I am missing?

The reason I am investigating this is because we have a case where we would want to prioritize som search results within a given product list, which I can’t find a way of doing right now.

Regards,
Felix

Litium version: 8.20.3

2

The boost field does make sense only in the context where multiple values are given — especially when:

  • You’re OR-ing multiple values, like multiple productList entries, multiple categories, etc.
  • Products might belong to more than one list or category.
  • You’re relying on relevance scoring to rank those hits.

In your scenario:

  • You’re passing a single productList, category, or priceList → which acts as a hard filter.
  • The boost field has no effect in this context — because all remaining products already match that single value.
  • Hence, no opportunity for boosting to affect the outcome.

If you want to prioritize some products within a given productList, you have a few options:

Option 1: Use boost in Combination with Other Lists

E.g., set up an additional list called top-priority-products and include it like this:

json

"productList": [
  { "systemId": "main-list", "boost": 1.0 },
  { "systemId": "top-priority-products", "boost": 5.0 }
]

This way:

  • You still filter to a relevant scope.
  • But within that, products in top-priority-products rank higher.

Option 2: Use Custom Fields (like a “ranking” or “priority” score)

  • Add a custom field like searchPriority to your products.
  • Use that in the search query with boost.
  • This gives you fine-grained control over ranking without relying solely on lists.
3

Thank you Vishnu, that seems like a reasonable description. I tried it but it does not seem like the storefront API supports multiple product lists.

Query:

query: {
      name: { value: "anslagstavla" }
      productList: {
        productListId: "productlistid-1"
        boost: 100
      }
      productList: {
        productListId: "productlistid-2"
        boost: 0
      }
    }

gives an error with message There can be only one input field named 'productList'..

4

The purpose of the boost field was to to be able to boost different sections of the category/product list but the model was changed and now we only supports one of each of these properties. The reason was to get it to work with sort.

If you have use-cases that it may be good to search of multiple of these, describe them in an idea at the https://ideas.litium.com

5

Hi Patric,

I don’t really understand what you mean by boosting different sections of the category/product list, can you give an example of that?

Not sure if this is really the way to go for our use case, what we really are looking for is adding custom sorting algorithms (in this case always show products from a certain product list higher in the search result). Boosting on one product list could be one option but I think that it could also introduce other issues for us.

Regards,
Felix

6

The purpose from the beginning was that you was able to filter on multiple categories or product lists on the same time, this was removed in early stage of the storefront api but the boost property was something that we didn’t think of to remove. Today they have no impact because you can only filter on one category or product list.

7

Okay, I see. So it is not possible right now to query for products that are either in CategoryA or CategoryB (or the same for product lists)? If so, I can see the use for that.