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
Visit our Postman collection to test this request.
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=10Sample 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