Skip to main content

Personalization

note

Personalization is enabled by Marqo per index, and separately per surface. Contact your Marqo account manager to turn it on.

Personalization biases ranking toward the products a shopper has recently engaged with. It is driven entirely by the event tracking pixel: you send a userId on the request, and Marqo looks up that shopper's recent interactions and ranks accordingly.

What Marqo captures​

The pixel records three interaction types that carry a product id, and only these three feed personalization:

EventMeaning
ClickEventThe shopper opened a product
AddToCartEventThe shopper added a product to their cart
PurchaseEventThe shopper bought a product

From those events Marqo takes the shopper's most recently interacted-with products, newest first, and removes duplicates. That list of product ids is the whole shopper profile. There is no separate model of brand affinity, price band, size, colour, device or session behaviour, and search queries are not part of it.

Because the profile is a list of recent products, personalization reflects what a shopper did in the last few sessions rather than a long-term taste model. Nothing needs to be submitted by hand, and there is no profile to build or maintain.

How it is applied​

Personalization works differently depending on the surface, but every surface is keyed on the userId you send.

SurfaceHow ranking changes
SearchThe shopper's recent products are attached to the request as a ranking signal, and the closeness weights configured for your index are added to the score. Which products are retrieved does not change; only their order does.
CollectionsOn a browse, the shopper's two most recent products are used as context and the request is run as a hybrid search biased toward them.
Similar products and Complementary productsThe same recent-products ranking signal as search, applied to the shelf. Each of these two shelves is enabled separately.
For YouPersonalized by construction: the shopper's recent products are the seed the shelf is built from, so it needs no separate setting beyond a linked pixel.

By default Marqo uses the shopper's three most recent products on search and the recommendation shelves, and exactly two on a collection browse. For You uses a longer history. How strongly the signal moves results is set per index by Marqo, through the closeness weights applied to the score. There is no per-request strength control.

Turning it on​

Four things must be true before a request is personalized:

  1. Your index has an event tracking pixel linked, and the pixel is recording interactions.
  2. Marqo has enabled personalization for the surface you are calling. Search, similar products and complementary products are enabled independently of one another.
  3. The request carries a userId. Send the same identifier you send to the pixel, otherwise Marqo cannot match the shopper. A sessionId may be sent alongside it to refine the lookup, but on its own it does nothing.
  4. The shopper has enough history. Search and the recommendation shelves need at least two recent products by default, and a collection browse needs two.

Knowing whether it applied​

Personalization never fails a request. When it cannot apply, the response is still a normal 200 with unpersonalized results, so check the response rather than assuming.

  • The x-marqo-results-personalized response header is true or false on every request that carried a userId.
  • The personalized body field carries the same answer on search, on a collection browse, and on the similar and complementary shelves. It is absent on a sorted browse and on a search within a collection, where the header is the reliable signal. For You reports the outcome in the header only.

When personalization does not apply​

A request that carries a userId is served unpersonalized, with false reported, in any of these cases:

  • A sort is applied. sortBy is an explicit ordering instruction, so it takes precedence and personalization is skipped.
  • The index is not configured for it, or the surface has not been enabled, or no pixel is linked.
  • The shopper has too little history, including a shopper Marqo has not seen before.
  • The search is not a hybrid search. On the search endpoint, personalization applies only to an explicitly hybrid search configuration. If your index is configured for lexical-only retrieval, personalization cannot attach to the request.
  • The shopper's interaction history could not be fetched in time. Marqo gives the lookup a short budget, and a request that exceeds it is served unpersonalized. The lookup still completes in the background, so the same shopper's next request usually is personalized.
  • Every product in the shopper's history has since been deleted from the index. The request is retried without personalization rather than failing.

Caching​

A response that was actually personalized is never served from cache. A request carrying a userId that was not personalized is cached normally, so a userId alone does not guarantee a fresh response.

Privacy​

Marqo stores the interactions the pixel sends and matches them by the userId you supply. You choose that identifier, so you control whether it is tied to a signed-in account or to an anonymous browser identity, and whether to send one at all. To exclude a shopper from personalization, omit the userId from their requests.