Complementary Recommendations

Complementary recommendations

POST /indexes/{index_name}/recommendations/complementary

Purpose

Drive cross-sell by suggesting items frequently purchased or interacted with together. Complementary recommendations use machine learning to analyze purchase patterns, co-occurrence data, and product relationships to identify items that naturally pair with what the customer is already considering. Unlike similar recommendations that offer alternatives, complementary suggestions work synergistically with the base product to optimize for increased Average Order Value (AOV).

When to use

• Cross-sell opportunities: When customers are viewing or have added items that commonly pair with accessories, add-ons, or complementary products
• Bundle optimization: To suggest logical product combinations that increase basket size
• Cart abandonment recovery: To add value perception through relevant add-ons

Example uses

Use Case	Description	Input Products	Business Impact
Frequently Bought Together	Suggest items commonly purchased alongside the current product	Main product from PDP or cart	Drives cross-sell, leverages proven purchase patterns
Cart Completion	Recommend add-ons or accessories before checkout	All items currently in cart	Last-chance revenue boost, reduces post-purchase regret
Bundle Suggestions	Show products that work together as a logical set or package	Primary product or category anchor	Creates value perception, increases basket size
Cross-Sell Opportunities	Suggest complementary items from different categories	Any product as anchor point	Diversifies purchase, introduces new product categories

Event types (eventType)

The eventType parameter controls which co-interaction signal is used to generate recommendations:

• ClickEvent — "customers also viewed". Based on products that users frequently view together.
• AddToCartEvent — "customers also added to cart". Based on products that users frequently add to cart together.
• PurchaseEvent — "frequently bought together". Based on products that users frequently purchase together.

How multiple docIds work

When multiple docIds are provided, results are products that are complementary to any of the input items, ranked by the sum of co-interaction frequencies across all input items. This is useful for checkout-page cross-sell where you want to recommend items based on the entire cart.

Example (cURL)

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/${index_name}/recommendations/complementary \
  -H "x-marqo-index-id: ${MARQO_INDEX_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "docIds": ["shirt_123"],
    "eventType": "PurchaseEvent",
    "limit": 6
  }'

Multi-doc example (checkout cross-sell)

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/${index_name}/recommendations/complementary \
  -H "x-marqo-index-id: ${MARQO_INDEX_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "docIds": ["shirt_123", "pants_456"],
    "eventType": "PurchaseEvent",
    "minFrequency": 5,
    "limit": 4,
    "filter": "in_stock:true"
  }'

Parameters

Filters use the Marqo Filter DSL. Note: Results automatically exclude the input item(s) where applicable. The endpoint uses strict validation — any unrecognized parameters will return a 400 error.

Name	Type	Required	Description	Example
docIds	array[string]	yes	An array of 1-10 item IDs to anchor the complements.	["shirt_123"]
eventType	string	yes	The type of co-interaction to base recommendations on. One of ClickEvent, AddToCartEvent, PurchaseEvent.	"PurchaseEvent"
limit	integer	no	Max number of results (default 10).	6
offset	integer	no	Pagination offset.	0
filter	string	no	Constrain by stock, brand, category, price ranges. See Marqo Filter DSL.	"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"]
minFrequency	integer	no	Minimum number of co-interactions required for a product to appear in results. Acts as a quality threshold — set higher to only surface strong signals. Defaults to 1.	5
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 checkout). If the specified profile does not exist, Marqo will fall back to the default configuration.	"pdp_default"