Complete the Look Recommendations

Complete the look recommendations

POST /indexes/{index_name}/recommendations/complete-the-look

Purpose

Surface items that pair with the product a shopper is viewing — "complete the look" / "pairs well with" — rather than alternatives to it. A bikini top surfaces its matching bottoms, cover-ups and bags; a board short surfaces a rash guard; a tech suit surfaces goggles, a cap and anti-fog. The goal is a cohesive, cross-category upsell that raises attach rate and Average Order Value (AOV), complementing (not duplicating) the alternatives shown under Similar Items.

Background

Complete-the-look is content-based: it combines embedding similarity to the viewed product with a curated complement mapping (configured per index by Marqo) that says which product families pair with which. Because it works from product content rather than interaction history, it produces on-theme results on every product detail page — including brand-new products and long-tail items with little or no engagement data.

This makes it distinct from the other recommendation endpoints:

Endpoint	Returns	Basis
/recommendations/similar	Alternatives / substitutes to the item	Content (vector similarity)
/recommendations/complementary	Items frequently bought / viewed together	Engagement (co-interaction signals)
/recommendations/complete-the-look	Items that pair with the item (cross-category)	Content (similarity + curated complement mapping)

complete-the-look is a good primary source where engagement data is sparse, and a good fallback beneath /complementary where it is rich — both can share the same request filter.

When to use

• PDP "Pairs Well With" / "Complete the Look" shelf: cross-category upsells alongside the viewed product.
• Cold-start / long-tail products: a full, on-theme shelf even with zero engagement history.
• Guaranteed-filled shelf: the endpoint never returns an empty result set (see How it works).

Example uses

Use Case	Description	Input Products	Business Impact
PDP "Pairs Well With"	Show items that complete the outfit/set next to the viewed product	Current product being viewed	Raises attach rate & AOV with coordinated items
New / long-tail products	Populate the shelf for products with no purchase history	The new product as anchor	On-theme recs from day one, no cold-start gap
Content-based fallback	Fill the complementary shelf where co-purchase data is thin	Product from PDP	Guarantees a full, relevant shelf

How it works

• Complement targeting — the viewed product's category resolves to a product family; results are restricted to that family's curated complement families, so the true counterpart ranks first by embedding similarity (e.g. a solid navy top surfaces the matching solid navy bottom first).
• No self / no variants — the product itself and its variants are excluded, and results are collapsed by product parent so each product appears once (no colour/size duplicates).
• Never empty — if the complement pool is thin, the endpoint tops up with broader on-theme similarity (still excluding the item's own family) so the shelf always fills to limit.
• Optional diversification — results can be rotated across complement families (e.g. a bottom, then a cover-up, then a bag, rather than five bottoms). This, the complement mapping, and optional score tuning are configured per index — contact Marqo to set up or tune complete-the-look for your catalog.

Filtering (gender, availability, etc.)

The endpoint applies exactly the filter you send (Marqo Filter DSL), in addition to its own product/variant exclusion. Pass the constraints the shelf needs — most importantly in-stock and, on gendered catalogs, the opposite-gender exclusion for the viewed product — so out-of-stock or mismatched-gender items don't appear. For example, on a women's PDP: anyVariantInventoryAvailable:true AND NOT gender:(Men's).

Example (cURL)

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/${index_name}/recommendations/complete-the-look \
  -H "x-marqo-index-id: ${MARQO_INDEX_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "documentIds": ["bikini_top_123"],
    "limit": 6,
    "filter": "in_stock:true AND NOT gender:(Men'\''s)"
  }'

Parameters

Filters use the Marqo Filter DSL. Results automatically exclude the input item(s) and their variants. The endpoint uses strict validation — any unrecognized parameters return a 400 error.

Name	Type	Required	Description	Example
documentIds	array[string]	yes	An array of 1–10 item IDs to anchor the recommendations on (typically the viewed product).	["bikini_top_123"]
limit	integer	no	Max number of results to return. Defaults to 10.	6
offset	integer	no	Offset for pagination.	0
filter	string	no	Server-side constraints (e.g. in-stock, opposite-gender, brand, price ranges). See Marqo Filter DSL. Applied in addition to the endpoint's own product/variant exclusion.	"in_stock:true"
attributesToRetrieve	array[string]	no	Attributes to return in the response for each document. If not specified, all attributes are returned.	["title", "price", "image_url"]
sortBy	object	no	Custom result ordering. When set, it takes precedence over the endpoint's similarity ranking (and disables diversification). Omit to rank by pairing relevance.	{ "fields": [{ "fieldName": "price", "order": "asc" }] }
userId	string	no	Optional user identifier for personalization.	"abc123"
sessionId	string	no	Optional session identifier.	"xyz789"
profileId	string	no	A named configuration profile for the request. Profiles allow fine-tuned configurations tailored to specific use cases (e.g. different behaviour on PDP vs collection pages). If the specified profile does not exist, Marqo falls back to the default configuration.	"pdp_default"