Recommendation Widgets

Recommendation widgets

POST /api/v1/indexes/{index_name}/recommendations/widgets/{widget_id}

Purpose

Serve a recommendation shelf that a merchandiser built and named in the Marqo console, such as a "New arrivals" carousel on the home page, a "Staff picks" grid on a landing page, or a personalised "For you" row. The storefront asks for the widget by its ID and Marqo returns the products the widget's source and merchandising rules produce. Merchandisers change what a widget shows from the console, without a theme or code change.

Background

The other recommendation endpoints are algorithms seeded by the request: similar and complementary take product IDs, For You takes a shopper. A widget is a configured object instead. Each widget has a label, an ID the storefront references it by, a source that fills it, and its own merchandising rules (pins, exclusions, boosts and buries, filters, and schedules) that apply only to that widget.

Source	What fills the widget	Typical use
Search query	The results of a search query, merchandised with the widget's rules	"New arrivals", "Under $50", "Gifts for dad"
Collection	The products of a collection, merchandised with the widget's rules	"Best of bedding" on the home page
Hand-picked	Only what the merchandiser pins, in the order they chose, from anywhere in the catalog. Filters, boosts and buries shape anything after the pins	Editorial or campaign sets
For You	Personalised per shopper from their tracked events. Pinned products always appear; the remaining slots are filled per shopper at request time	Home page "For you" row

When to use

Home page and landing page shelves: Recommendations that are not tied to a product the shopper is viewing
Campaign placements: Shelves a merchandiser retargets, reorders, or schedules without a deploy
Personalised rows with guaranteed placements: A For You widget where certain products must always appear
Any placement rendered from an ID: One theme block that renders whichever widget a merchandiser assigns to it

Example uses

Use Case	Description	Source	Business Impact
Home page "New Arrivals"	Show recently added products, filtered to the last week and in stock	Search query	Keeps the home page fresh without theme edits
Seasonal campaign shelf	Hand-pick the campaign's hero products in a fixed order, scheduled for the campaign window	Hand-picked	Guarantees placement for promoted items
Collection spotlight	Feature a collection on the home page with a bestseller pinned first	Collection	Drives traffic into a priority category
Personalised "For You" row	Fill a row per shopper, with a new launch pinned to position 1	For You	Combines personalisation with merchandising control
Landing page grid	Render a widget as a grid rather than a carousel; the API is layout-neutral	Any	One widget serves any layout

In the Marqo console open Merchandising → Recommendation Rules → Widgets and select the index.
Click Create Widget and give it a Label, an ID, and a Source. A Search query widget also takes the query; a Collection widget takes the collection.
Merchandise it as you would a search or collection: pin and exclude products, boost and bury, filter, and schedule rules.
Publish. A widget is served once it has published rules. Until then the endpoint returns 404 for its ID.

Published changes reach the API within five minutes: rules are exported to the edge on a five-minute schedule. The same applies when a widget is deleted, after which its ID returns 404.

The ID is what the storefront sends in the path. It is chosen by the merchandiser, is unique within the index, and is used exactly as authored (case-sensitive). IDs may contain letters, digits, _ and -, must start with a letter or digit, and are at most 64 characters long, so they are always URL-safe.

tip

A widget's merchandising rules are independent: the index-wide merchandising rules (its pins, exclusions, boosts and buries) do not apply to a widget, only the rules authored on the widget itself.

The index's search configuration still applies, exactly as it does on /search and /collections. That includes the configured filter, score modifiers, collapse fields, attribute list and any matching query rules, so a widget cannot escape a global filter such as published:true. A For You widget runs under the For You configuration layered over the search configuration.

For You widgets cannot be previewed in the console, since their unpinned slots are chosen per shopper at request time.

Example (cURL)

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/${index_name}/recommendations/widgets/new-arrivals \
  -H "x-marqo-index-id: ${MARQO_INDEX_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 8,
    "filter": "in_stock:true"
  }'

For You example

A For You widget needs the shopper, exactly as the For You endpoint does. It requires the event tracking pixel to be installed on the store.

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

A shopper Marqo cannot personalise for yet (no tracked events) still gets the widget: its pinned products first, then the widget's rules applied across the catalog. The x-marqo-results-personalized response header says which happened.

A For You widget returns a single synthesised page, so totalHits equals the number of hits returned rather than a catalog-wide count.

Parameters

The widget is named by the path. The body carries only per-request options and uses strict validation: any unrecognised parameter returns a 400 error. Filters use the Marqo Filter DSL and apply in addition to the widget's own filter rules.

Name	In	Type	Required	Description	Example
widget_id	path	string	yes	The widget's ID as set in the console. Used exactly as authored (case-sensitive).	`new-arrivals`
limit	body	integer	no	Max number of results to return. Defaults to the index's configured search limit (12 if none is set); 10 for a For You widget.	`8`
offset	body	integer	no	Offset for pagination.	`0`
filter	body	string	no	Server-side constraints (e.g., `in_stock`, price ranges, brand, category). See Marqo Filter DSL.	`"in_stock:true"`
attributesToRetrieve	body	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"]`
userId	body	string	For You widgets	User identifier for personalisation. Required for a For You widget and ignored by the other sources, so a storefront block can always send it.	`"abc123"`
sessionId	body	string	no	Optional session identifier. For You widgets only.	`"xyz789"`
interactionTypes	body	array[string]	no	Types of interactions to consider (ClickEvent, AddToCartEvent, PurchaseEvent). Default: all types. For You widgets only.	`["ClickEvent", "AddToCartEvent"]`

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. For Search query, Collection and Hand-picked widgets, limit plus offset must not exceed 10,000.

Response (example)

{
  "hits": [
    {
      "_id": "sku_38702",
      "_score": 0.7412,
      "title": "Linen Duvet Cover",
      "price": 249.0,
      "image_url": "https://cdn.example.com/sku_38702.jpg"
    }
  ],
  "limit": 8,
  "offset": 0,
  "totalHits": 143,
  "processingTimeMs": 41
}

Field	Type	Description
hits	array[object]	The widget's documents, each with `_id`, `_score` and the retrieved attributes.
limit	integer	The `limit` applied to the request.
offset	integer	The `offset` applied to the request.
totalHits	integer	Number of matching documents. For a For You widget this is the number of hits returned, not a catalog-wide count.
processingTimeMs	integer	Server processing time in milliseconds.

These are the only fields the endpoint returns. Unlike a search response there is no facets, query, personalized or redirect field, so a renderer shared with the search page should not depend on them.

Header	Description
`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.
`x-marqo-results-personalized`	For You widgets only. `true` when the results were built from the shopper's own events; `false` when the widget fell back to its rules alone.

Errors

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

Status	Message
400	`Unrecognized param(s): '<name>'` for any parameter not listed above
400	`Parameter 'userId' must be a non-empty string` when `userId` is present but empty
400	A message from the request validator when a value fails its constraint, for example an unknown `interactionTypes` value
400	`Custom recommendations failed: Parameter 'userId' is required for a For-You carousel` when a For You widget is called without `userId`
400	`Custom recommendations failed: Personalized recommendations not configured, please contact Marqo to enable them` for a For You widget on an index that has no event tracking pixel or has personalisation switched off
400	`Custom recommendations failed: <reason>` when the underlying search rejects the request (for example, an invalid `filter`)
404	`Widget '<id>' not found`: no widget with that ID on the index, the widget has no published rules yet, or merchandising is not enabled on the index

Failures raised while the widget is being served carry the Custom recommendations failed: prefix. Request validation messages and the 404 do not.

note

Treat a 404 as "render nothing". It is the expected response for a widget a merchandiser has created but not yet published, or has since deleted.