User Featured Recommendations

For You recommendations

POST /api/v1/indexes/{index_name}/recommendations/for-you

Purpose

Surface a product shelf built from the products a shopper has actually interacted with. The endpoint reads the shopper's tracked clicks, cart additions and purchases and returns products similar to the ones they engaged with most recently, so the shelf reflects demonstrated interest rather than a guess.

Background

The event tracking pixel records three kinds of product interaction: ClickEvent, AddToCartEvent and PurchaseEvent. This endpoint takes the shopper's most recently interacted-with products and uses them as the seed for a similarity search across the index, so the shelf follows the shopper's recent behaviour and refreshes as they browse.

When to use

Homepage personalization: Show tailored content for returning visitors and logged-in users
Email marketing: Create personalized product recommendations in newsletters and campaigns
Account dashboards: Display relevant suggestions in user profiles and account pages
Re-engagement campaigns: Target users with products based on their historical preferences

Example uses

Use Case	Description	Interaction Source	Business Impact
Homepage "For You" Section	Display personalized recommendations on homepage for logged-in users	All three interaction types	Increases engagement, improves homepage relevance
Email Recommendations	Include "Based on Your Purchases" or "You Might Like" in email campaigns	`PurchaseEvent`	Drives return visits, increases email CTR
Account Dashboard	Show "Recommended for You" in user account or profile pages	All three interaction types	Extends session time, improves loyalty
Retargeting Campaigns	Target users with ads featuring products aligned with their preferences	`ClickEvent` and `AddToCartEvent`	Improves ad relevance, increases conversion rates
Mobile App Personalization	Create personalized product feeds within mobile applications	All three interaction types	Enhances app engagement, drives mobile sales

Input sources (interaction types)

The shelf is seeded from tracked product interactions, and only these three types are available. Use interactionTypes to narrow the seed to a subset; the default uses all three.

Interaction type	Recorded when
`PurchaseEvent`	The shopper bought the product.
`AddToCartEvent`	The shopper added the product to their cart, whether or not they bought it.
`ClickEvent`	The shopper clicked through to the product.

Only the products themselves are used, most recent first. Search queries, page dwell time and other engagement signals are not part of the seed.

Example (cURL)

curl -X POST "https://ecom.marqo-ep.ai/api/v1/indexes/product-catalog/recommendations/for-you" \
  -H "x-marqo-index-id: ${MARQO_INDEX_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "abc123",
    "limit": 12
  }'

Prerequisites

This endpoint builds the shelf from the shopper's tracked events, so the event tracking pixel must be installed on the store and personalisation must be enabled for the index. Otherwise every request returns a 400 (see Errors).

Parameters

Filters use the Marqo Filter DSL. The endpoint uses strict validation: any unrecognised parameter returns a 400 error.

Name	Type	Required	Description	Example
userId	string	yes	Shopper identifier, as sent to the event tracking pixel. Must be a non-empty string.	`"abc123"`
interactionTypes	array[string]	no	Types of interactions to consider (`ClickEvent`, `AddToCartEvent`, `PurchaseEvent`). Default: all types.	`["ClickEvent", "AddToCartEvent"]`
limit	integer	no	Max number of results to return. Defaults to 10.	`12`
offset	integer	no	Offset for pagination. Defaults to 0.	`0`
filter	string	no	Server-side constraints (e.g., `in_stock`, price ranges, brand, category). See Marqo Filter DSL.	`"in_stock:true"`
attributesToRetrieve	array[string]	no	Attributes to return for each document. If omitted, the attribute list configured for the index is returned, the same default as search.	`["title", "price", "image_url"]`
sortBy	object	no	Custom result ordering, in the same shape as the search `sortBy`. Fields from the request take precedence over any sort configured for the index.	`{ "fields": [{ "fieldName": "price", "order": "asc" }] }`
sessionId	string	no	Shopper session identifier, used together with `userId` to look up tracked events.	`"xyz789"`
profileId	string	no	A named search configuration profile for the request. If the profile does not exist, Marqo falls back to the default configuration.	`"home_default"`

documentIds and merchandisingProfileId are not accepted on this endpoint.

limit and offset must be whole, non-negative numbers. The API does not check this itself: a fractional or negative value is passed to the search engine, which rejects the request.

note

Merchandising rules do not apply to this endpoint. To combine a personalised shelf with pins, exclusions or boosts, create a For You widget instead.

Response (example)

{
  "hits": [
    {
      "_id": "sku_51230",
      "_score": 0.8127,
      "title": "Merino Crew Sweater",
      "price": 129.0,
      "image_url": "https://cdn.example.com/sku_51230.jpg"
    }
  ],
  "processingTimeMs": 71,
  "limit": 12,
  "offset": 0
}

Field	Type	Description
hits	array[object]	The recommended documents, each with `_id`, `_score` and the retrieved attributes.
processingTimeMs	integer	Server processing time in milliseconds.
limit	integer	The `limit` applied to the request.
offset	integer	The `offset` applied to the request.

There is no totalHits field. Whether the results were personalised is reported in a header, not in the body.

Header	Description
`x-marqo-results-personalized`	Always present. `true` when the shelf was built from the shopper's tracked events; `false` when the endpoint fell back to a regular search (see below).
`x-marqo-cache-hit-count`, `x-marqo-cache-miss-count`	How many of the underlying searches were served from cache and how many were not.

Fallback when the shopper cannot be personalised

When the shopper has no tracked events (or none of the requested interactionTypes), when their tracked products no longer exist in the index, or when their event history cannot be fetched in time, the endpoint does not return an error. It returns a regular search response for the whole index instead, with the other request parameters (such as filter and limit) applied, and x-marqo-results-personalized: false. That response has the search response shape, including totalHits, facets and query, and carries the x-marqo-cache-hit header. Clients should handle both shapes, for example by rendering hits and ignoring fields they do not expect.

The fallback response carries x-marqo-cache-hit in place of the x-marqo-cache-hit-count and x-marqo-cache-miss-count headers.

A personalised shelf is assembled from several searches run in parallel. If some of them fail but at least one succeeds, the endpoint returns 200 with the results it has and reports x-marqo-results-personalized: false, rather than falling back to a whole-index search.

Errors

Error responses have the body {"error": "<message>"}.

Status	Message
400	`Parameter 'userId' is required and must be a non-empty string`
400	`Personalized recommendations not configured, please contact Marqo to enable them` when the index has no event tracking pixel or personalisation is switched off
400	`Unrecognized param(s): '<name>'` for any parameter not listed above
400	A message from the request validator when a value fails its constraint, for example an `interactionTypes` entry that is not one of the three event types

For You recommendations​

Purpose​

Background​

When to use​

Example uses​

Input sources (interaction types)​

Example (cURL)​

Prerequisites​

Parameters​

Response (example)​

Fallback when the shopper cannot be personalised​

Errors​