Complementary

Complementary recommendations

POST /indexes/{index_name}/recommend

Purpose

Drive cross-sell by suggesting items frequently purchased together or that complete a set/look. These recommendations optimize for increased Average Order Value (AOV) by identifying products that naturally pair with what the customer is already considering, without competing for their attention or suggesting alternatives that might pull them away from their current selection.

Background

Complementary recommendations use machine learning to analyze purchase patterns, co-occurrence data, and product relationships to identify items that enhance or complete the customer's current selection. Unlike similar recommendations that offer alternatives, complementary suggestions work synergistically with the base product to create a more complete purchase experience.

When to use

• Cross-sell opportunities: When customers are viewing or have added items that commonly pair with accessories, add-ons, or complementary products
• Complete-the-look scenarios: For fashion, home décor, or lifestyle products where customers often purchase coordinated items
• 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
Complete the Look	Show items that naturally go together to create a cohesive style or set	Current item being viewed	Increases AOV, improves customer satisfaction
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

Input products (document_ids)

• PDP Context: Use the current product being viewed to suggest items that pair well
• Cart Context: Include all cart items to find complements that work with the entire selection
• Multi-item Context: Pass multiple related items (recent views, cart additions) to find products that complement the overall shopping intent
• Best Practice: Use 3-5 most relevant products as input to maintain focus and relevance

Example (cURL)

curl -X POST "https://api.marqo.ai/indexes/product-catalog/recommend" \
  -H "Authorization: Bearer $MARQO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": ["shirt_123"],
    "method": "complementary",
    "limit": 6
  }'

Parameters

Filters use the Marqo Filter DSL. Note: Results automatically exclude the input item(s) where applicable.

Name	Type	Required	Description	Example
method	string	yes	Recommendation method identifier.	"complementary"
document_ids	array[string]	yes	Input item IDs to anchor the complements.	["shirt_123"]
limit	integer	no	Max number of results (default 10).	6
offset	integer	no	Pagination offset.	0
filters	object	no	Constrain by stock, brand, category, price ranges. See Marqo Filter DSL.	{ "in_stock": true }
user_id	string	no	Optional user identifier.	"abc123"
session_id	string	no	Optional session identifier.	"xyz789"