Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Insider One Recommendation Algorithm Descriptions API
version: 1.0.0
description: 'Smart Recommender algorithms served over HTTP: similar, complementary, trending, top sellers, user-based and more.'
contact:
name: Insider One Support
email: support@useinsider.com
url: https://academy.insiderone.com/docs/insider-one-apis-1
termsOfService: https://insiderone.com/terms-of-use/
servers:
- url: https://recommendation.api.useinsider.com
tags:
- name: Algorithm Descriptions
paths:
/v2/chef:
get:
operationId: chef
summary: Chef
tags:
- Algorithm Descriptions
description: 'Chef is an automated recommendation algorithm that automatically identifies the best mixed strategy by testing the most popular items, top sellers, user-based, highest-discounted, new arrivals, and trending items algorithms to improve conversion rates. In a mixed strategy, you manually choose an algorithm for each slot. Chef, instead, chooses the best combination by automatically evaluating the algorithms'' performance.
Endpoint
GET https://recommendation.api.useinsider.com/v2/chef
Query Parameters
Parameter
Sample Value
Description
Data Type
Required
partnerName
mybrand
Partner Identifier, which is assigned by Insider One. You can use PartnerID as well.
String
Yes
locale
us_US
Language or region of the site.
String
Yes
platform
web
It is the requested platform. Its value can be web and app. Web comes by default.
Enum
No
currency
USD
Shows products with the specified currency.
String
No
userId
testUser
User identifier, which is assigned by Insider One.
String
No
hp
false, true or 0, 1
Makes affinities affect the products of the response. The default is false.
Boolean
No
categoryList
["Tops","Shirts"]
Category filter of the products
filter
Smart Recommender filtering. There can be more than one filter parameter.
String
No
details
true
Adds details to the products of the response.
Boolean
No
shuffle
false
Shuffles the products of the response.
Boolean
No
getGroupProducts
true
Shows variant products under the products of the response.
Boolean
No
groupProductsFields
Adds these fields to the variant products’ details.
String
No
excludeVariants
true
Exclude variants from the response.
Boolean
No
excludeViewDay
30
After how many days viewed products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
excludeViewItem
10
How many viewed products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
excludePurchaseDay
30
After how many days purchased products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
excludePurchaseItem
10
How many purchased products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
country
Italy
Requested country information
String
No (Only for Location Based Top Sellers usage in Mixed Strategy)
city
Milan
Requested city information
String
No (Only for Location Based Top Sellers usage in Mixed Strategy)
dayLimit
7
Threshold last update day value for Publisher partners The default is 2 days.
Integer
No
ulv
true, false
Enables User Last Visit to affect recommendation results
Boolean
No
Sample Request
The sample below shows a request to Chef, an automated recommendation strategy that picks the best-performing mix (popular items, top sellers, user-based, highest-discounted, new arrivals, trending, etc.) per slot—no manual algorithm selection required.
https://recommendation.api.useinsider.com/v2/chef?partnerName={PartnerName}&locale={Locale}
Sample Response
{
"success": true,
"total": 16,
"types": {
"mpop": 14,
"mvop": 2
},
"data": [
"ABC1234",
"ABC1243",
"ABC1234",
"ABC1235",
"ABC1237",
"ABC1230",
"ABC1263",
"ABC1209",
"ABC1256",
"CBA1234",
"CBA1233",
"CBA1236",
"CBA1239",
"CBA1221",
"CBA1209",
"CBA1247"
]
}
Fallback Algorithms
The Chef algorithm doesn''t have a specific fallback mechanism; instead, fallback algorithms are determined by the individual algorithms selected by Chef.'
security:
- RequestToken: []
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
/v2/complementary:
get:
operationId: complementaryProducts
summary: Complementary Products
tags:
- Algorithm Descriptions
description: 'The Complementary Products algorithm surfaces products that go well with the one the shopper is currently viewing, items that complete the look, set, or use case rather than replace it (e.g., a belt for trousers, a case for a phone, a lamp for a sofa).
It uses a catalog-aware map of complementary category relationships generated by a language model from your category tree, so it works even on catalogs with little or no purchase history. Performs optimally on product detail and cart pages.
Endpoint
GET https://recommendation.api.useinsider.com/v2/complementary
Query Parameters
Parameter
Sample Value
Description
Data Type
Required
partnerName
mybrand
Partner Identifier assigned by Insider One. You can use PartnerID as well.
String
Yes
locale
us_US
Locale of requested product catalog
String
Yes
productId
1068
The reference product for which the complement is computed
String
Yes
currency
USD
Product currency. If no value is set, the default currency in your settings is used.
String
No
size
10
Response items. Valid values are 0 to 100.
Integer
No
categoryList
[“Clothes”]
Category filter of the products
Array
No
userId
a1b2c3d4
User identifier; enables personalization boosts when provided
String
No
platform
web
Requested platform (default: web)
Enum
No
details
true
Adds details to the products of the response
Boolean
No
excludeVariants
true
Hides color/size variants of the same base product
Boolean
No
shuffle
false
Shuffles the products of the response
Boolean
No
filter
[in_stock][=][true]
Restricts results by fields such as price, brand, color, gender, in_stock, or category
String
No
hp
true
Hyper-personalization flag. Re-ranks results using the shopper''s attribute preferences
Boolean
No
getGroupProducts
true
Returns all color/size variants grouped under each recommended product
Boolean
No
groupProductsFields
product_attributes.color,price
Comma-separated list of fields to include in the grouped variants; products missing any listed field are dropped
String
No
getAllGroupProductsFields
true
Returns all variant fields without dropping products for missing fields; automatically enables getGroupProducts
Boolean
No
excludeViewDay
30
Days before excluding previously viewed products
Integer
No
excludeViewItem
100
Number of viewed products to exclude
Integer
No
excludePurchaseDay
30
Days before excluding previously purchased products
Integer
No
excludePurchaseItem
100
Number of purchased products to exclude
Integer
No
Sample Request
The sample below shows a request to Complementary Products, the algorithm that suggests items frequently bought or viewed alongside the anchor product.
https://recommendation.api.useinsider.com/v2/complementary?partnerName={PartnerName}&locale={Locale}&productId={ABC123}&size=10
Sample Response
{
"success": true,
"total": 10,
"types": { "cp": 10 },
"data": [
"649517_49890",
"568334_49053",
"639714_49677"
]
}
Fallback Algorithms
When Complementary Products results are insufficient, these algorithms fill the response:
Purchased Together
Most Popular Items'
security:
- RequestToken: []
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
/v2/highest-discounted:
get:
operationId: highestDiscountedProducts
summary: Highest Discounted Products
tags:
- Algorithm Descriptions
description: 'The Highest Discounted Products algorithm recommends products based on their discount ratios, prioritizing those with higher discounts. It calculates the discount ratio for each product using the original and discounted prices. Recommended products will be sorted from highest to lowest discount for the given size. For each currency type, the discount ratio is calculated separately. This type of algorithm works best on main and category pages.
Endpoint
GET https://recommendation.api.useinsider.com/v2/highest-discounted
Query Parameters
Parameter
Sample Value
Description
Data Type
Required
partnerName
mybrand
Partner Identifier assigned by Insider One. You can use PartnerID as well.
String
Yes
locale
us_US
Locale of the requested product catalog
String
Yes
platform
web
Requested platform. Web comes by default.
Enum
No
currency
USD
Requested currency of the products. If no value is set, the default currency in your settings is used.
String
Yes
userId
a1b2c3d4
User identifier which is assigned by Insider One
String
No
hp
false, true, or 1, 0
Makes affinities affect products of the response. The default is false.
Boolean
No (Can only be used with userId)
size
50
Required number of items in response. Valid values are 0 to 100.
Integer
No
categoryList
[“Clothes”, “Skirts”]
Category filter of the products
Array (of string)
No
filter
Smart Recommender filtering. There can be more than one filter parameter.
String
No
details
true
Adds details to the products of the response
Boolean
No
shuffle
false
Shuffles the products of the response
Boolean
No
getGroupProducts
false
Shows variant products under the products of the response
Boolean
No
groupProductsFields
Adds these fields to the variant products’ details
String
No
excludeVariants
true
Exclude variants from the response
Boolean
No
excludeViewDay
30
After how many days viewed products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
excludeViewItem
10
How many viewed products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
excludePurchaseDay
30
After how many days purchased products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
excludePurchaseItem
10
How many purchased products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
productId
ABC123CBA
Current product ID
String
No
If you want to get top sellers products from the category or categories you want, specify either categoryList or category and subCategory.
Sample Request
The sample below displays a request for the Highest Discounted Products; the algorithm recommends products based on their discount ratios, prioritizing those with higher discounts.
https://recommendation.api.useinsider.com/v2/highest-discounted?partnerName={Partner Name}&locale={Locale}&size=5¤cy={Currency}
Sample Response
{
"success": true,
"total": 5,
"types": {
"hdop": 5
},
"data": [
"AB76543",
"AB54321",
"YZ76543",
"AB49876",
"AB01234"
]
}
Fallback Algorithms
If the products from the Highest Discounted Products are not enough to fill the response data, some fallback algorithms below fill it:
Highest discounted products of the category without excluding the right-most item in the categoryList'
security:
- RequestToken: []
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
/v2/last-purchased-together:
get:
operationId: purchasedWithLastPurchased
summary: Purchased with Last Purchased
tags:
- Algorithm Descriptions
description: 'The Purchased with Last Purchased algorithm is one of Insider One''s personalized algorithms. It recommends the purchased products along with the user’s last purchased product. Purchase events can be collected from Web, Mobile, and Offline (CRM) UCD events. It is available on Web Smart Recommender, API-based Recommender, and App Recommender.
Endpoint
GET https://recommendation.api.useinsider.com/v2/last-purchased-together
Query Parameters
Parameter
Sample Value
Description
Data Type
Required
partnerName
1000001
Partner Identifier assigned by Insider One. You can use PartnerID as well.
String
Yes
locale
us_US
Language or region of the site
String
Yes
currency
USD
Shows products with the specified currency
String
No
userId
a1b2c3d4
User identifier that is assigned by Insider One
String
Yes
platform
web
Requested platform. Web comes by default.
String
No
details
true
Adds item details to the response
Boolean
No
hp
false
Hyper-personalization activation
Boolean
No
size
50
Required number of items in response. The maximum allowed size is 100.
Integer
No
shuffle
false
Shuffle the products in the response
Boolean
No
excludeVariants
true
Exclude variants by the same group ID. If the panel setting is true for this feature, the parameter will always be true. Otherwise, it depends on the parameter. The default value is false.
Boolean
No
excludePurchaseDay
30
Exclude items the user purchased in X days
Integer
No
excludeViewDay
30
Exclude items the user viewed in X days
Integer
No
excludePurchaseItem
100
The number of purchased products to exclude
Integer
No
excludeViewItem
100
The number of viewed products to exclude
Integer
No
productId
ABC123CBA
Current product ID
String
No
filter
Smart Recommender filtering. There can be more than one filter parameter.
String
No
categoryList
[“Clothes”, “Skirts”]
Category filters of the product
Array (of string)
No
getGroupProducts
true, false
Shows variant products under the products of the response
Boolean
No
groupProductsFields
name, category
Adds these fields to the variant products’ details
String
No
dayLimit
7
Threshold last update day value for Publisher partners. The default is 2 days.
Integer
No
Sample Request
The sample below displays a request to Purchased with Last Purchased, one of Insider One’s personalized recommendation algorithms.
https://recommendation.api.useinsider.com/v2/last=purchased-together?partnerName={PartnerName}&locale={Locale}&userId={UserId}
Sample Response
{
"success": true,
"total": 10,
"types": {
"lpt": 10
},
"data": [
"QAZ-7890",
"XYZ-1234",
"QAZ-7899",
"XYZ-1233",
"QAZ-7898",
"XYZ-1243",
"QAZ-7891",
"XYZ-1223",
"QAZ-7892",
"XYZ-1342"
]
}
Fallback Algorithms
Because of its nature, the Purchased with Last Purchased Algorithm doesn’t have a fallback. However, you can always tune it by configuring the minimum number of products displayed in the Recommendation carousel under Recommendation Strategies.'
security:
- RequestToken: []
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
/v2/manual-merchandising:
get:
operationId: manualMerchandising
summary: Manual Merchandising
tags:
- Algorithm Descriptions
description: 'The Manual Merchandising algorithm retrieves product details manually specified and returns only in-stock products. It enables you to showcase specific products or content (e.g., for special days) from a list specified in the campaign configuration. In addition, only in-stock products will be displayed in the recommendation widget. This type of algorithm can be used on all page types to promote specific products.
Endpoint
GET https://recommendation.api.useinsider.com/v2/manual-merchandising
You need to write Product IDs as comma-separated in the productId parameter, such as productId=ed061306,287a4a89,8f0db743,69de9b05
Query Parameters
Parameter
Sample Value
Description
Data Type
Required
partnerName
mybrand
Partner Identifier assigned by Insider One. You can use PartnerID as well.
String
Yes
locale
us_US
Locale of requested product catalog
String
Yes
platform
web
Requested platform. Web comes by default.
Enum
No
currency
USD
Requested currency of the products. If no value is set, the default currency in your settings is used.
String
Yes
productId
ABC1234
The ID of the product whose complementary is requested
String
Yes
userId
testUser
User identifier which is assigned by Insider One
String
No
hp
false, true or 0, 1
Makes affinities affect products of the response. The default is false.
Boolean
No (Can only be used with userId)
size
50
Required number of items in response. Valid values are 0 to 100.
Integer
No
filter
Smart Recommender filtering. There can be more than one filter parameter.
String
No
details
true
Adds details to the products of the response
Boolean
No
shuffle
false
Shuffles the products of the response
Boolean
No
getGroupProducts
false
Shows variant products under the products of the response
Boolean
No
groupProductsFields
Adds these fields to the variant products’ details
String
No
excludeViewDay
30
After how many days viewed products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
excludeViewItem
10
How many viewed products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
excludePurchaseDay
30
After how many days purchased products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
excludePurchaseItem
10
How many purchased products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
includeOutOfStockItems
False, true, 0, or 1
Boolean flag to decide if out of stock products given in endpoint parameter should return in API response. The default is false.
Boolean
No
Sample Request
The sample below displays a request to the Manual Merchandising algorithm:
https://recommendation.api.useinsider.com/v2/manual-merchandising?partnerName={Partner Name}&locale={Locale}&productId=ABC12345,XYZ12345
Sample Response
{
"success": true,
"total": 2,
"types": {
"mm": 2
},
"data": [
"ABC12345",
"XYZ12345"
]
}
Fallback Algorithms
There is no fallback algorithm for this recommendation type, as only requested items are recommended.'
security:
- RequestToken: []
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
/v2/mixed:
get:
operationId: mixedStrategy
summary: Mixed Strategy
tags:
- Algorithm Descriptions
description: The Mixed Strategy algorithm creates a customized, mixed recommendation strategy that combines different recommendation types.
security:
- RequestToken: []
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
/v2/most-popular:
get:
operationId: mostPopularItems
summary: Most Popular Items
tags:
- Algorithm Descriptions
description: The Most Popular Items algorithm recommends items by analyzing the most popular products by page views.
security:
- RequestToken: []
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
/v2/most-valuable:
get:
operationId: mostValuableProducts
summary: Most Valuable Products
tags:
- Algorithm Descriptions
description: 'The Most Valuable Products algorithm recommends items based on their contribution to total revenue. It recommends products that generate more revenue across your site. Products are recommended based on the contribution to revenue and revenue per visit. This type of algorithm can be used on all page types.
Endpoint
GET https://recommendation.api.useinsider.com/v2/most-valuable
Query Parameters
Parameter
Sample Value
Description
Data Type
Required
partnerName
mybrand
Partner Identifier assigned by Insider One. You can use PartnerID as well.
String
Yes
locale
us_US
Locale of the requested product catalog
String
Yes
platform
web
Requested platform. Web comes by default.
Enum
No
currency
USD
Requested currency of the products. If no value is set, the default currency in your settings is used.
String
No
size
50
Required number of items in response. Valid values are 0 to 100.
Integer
No
categoryList
[“Clothes”, “Skirts”]
Category filter of the products
Array (of string)
No
filter
Smart Recommender filtering. There can be more than one filter parameter.
String
No
details
true
Adds details to the products of the response.
Boolean
No
shuffle
false
Shuffles the products of the response.
Boolean
No
getGroupProducts
false
Shows variant products under the products of the response
Boolean
No
groupProductsFields
Adds these fields to the variant products’ details
String
No
excludeVariants
true
Exclude variants from the response
Boolean
No
userId
a1b2c3d4
User identifier that is assigned by Insider One
String
No
excludeViewDay
30
After how many days should viewed products be excluded
Integer
No (Can be used only with userId)
excludeViewItem
100
How many viewed products should be excluded
Integer
No (Can be used only with userId)
excludePurchaseDay
30
After how many days should purchased products be excluded
Integer
No (Can be used only with userId)
excludePurchaseItem
100
How many purchased products should be excluded
Integer
No (Can be used only with userId)
hp
false
Makes affinities affect the products of the response
Boolean
No
productId
ABC123CBA
Current product ID
String
No
Sample Request
The sample below displays a request to Most Valuable Products, an algorithm that recommends items based on their contribution to total revenue:
https://recommendation.api.useinsider.com/v2/most-valuable?locale={Locale}¤cy={Currenct}&partnerName={PartnerName}
Sample Response
{
"success": true,
"total": 10,
"types": {
"mpop": 10
},
"data": [
"QAZ-7890",
"XYZ-1234",
"QAZ-7899",
"XYZ-1233",
"QAZ-7898",
"XYZ-1243",
"QAZ-7891",
"XYZ-1223",
"QAZ-7892",
"XYZ-1342"
]
}
Fallback Algorithms
If the products from Most Valuable Products are not enough to fill the response data, some fallback algorithms below fill it:
Most valuable products of the category, including the rightmost item in the categoryList.'
security:
- RequestToken: []
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
/v2/new-arrivals:
get:
operationId: newArrivals
summary: New Arrivals
tags:
- Algorithm Descriptions
description: The New Arrivals algorithm displays products that have been newly added to the website.
security:
- RequestToken: []
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
/v2/purchased-together:
get:
operationId: purchasedTogether
summary: Purchased Together
tags:
- Algorithm Descriptions
description: 'The Purchased Together algorithm recommends items by finding complementary products purchased by other users who have also purchased the user''s items. It generates recommendations based on products purchased in the same sessions and in the same locale over the past 30 days. After generating recommendations, the Purchased Together algorithm orders the results according to purchase frequency. With the Purchased Together algorithm, you can apply your users'' purchase patterns to your strategies. This type of algorithm works best on product and cart pages.
Endpoint
GET https://recommendation.api.useinsider.com/v2/purchased-together
When this algorithm is used on the cart page, its endpoint differs for multiple products. For example, three products (X, Y, Z) are in the cart. The recommendation API will return the complementary products for each product in the cart as X1, Y1, Z1, X2, Y2, Z2... respectively.
Query Parameters
Parameter
Sample Value
Description
Data Type
Required
partnerName
mybrand
Partner Identifier assigned by Insider One. You can use PartnerID as well.
String
Yes
locale
us_US
Locale of the requested product catalog
String
Yes
platform
web
Requested platform. Web comes by default.
Enum
No
currency
USD
Requested currency of the products. If no value is set, the default currency in your settings is used.
String
No
productId
ABC1234
The ID of the product whose complementary is requested
String
Yes
size
50
Required number of items in response. Valid values are 0 to 100.
Integer
No
categoryList
[“Clothes”, “Skirts”]
Category filter of the products
Array (of string)
No
filter
Smart Recommender filtering. There can be more than one filter parameter.
String
No
details
true
Adds details to the products of the response
Boolean
No
shuffle
false
Shuffles the products of the response
Boolean
No
getGroupProducts
false
Shows variant products under the products of the response
Boolean
No
groupProductsFields
Adds these fields to the variant products’ details
String
No
excludeVariants
true
Exclude variants from the response
Boolean
No
userId
testUser
User identifier which is assigned by Insider One
String
No
hp
true, false, or 0, 1
Makes affinities affect products of the response. The default is false.
Boolean
No
excludeViewDay
30
After how many days viewed products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
excludeViewItem
10
How many viewed products should be excluded. The default is -1.
Integer
No (Can only be used with userId)
Sample Request
The sample below displays a request to Purchased Together, an algorithm that recommends items frequently bought alongside the user’s selected product(s).
https://recommendation.api.useinsider.com/v2/purch
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/insider/refs/heads/main/openapi/insider-algorithm-descriptions-api-openapi.yml