Insider Algorithm Descriptions API

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.


    Derived by API Evangelist from Insider One''s own public Postman collection ("Insider One APIs", published at https://developers.insiderone.com/). Paths, methods, headers, query parameters and request/response examples are verbatim from that collection; nothing is invented. The 429 response is documented for all Insider One APIs on https://academy.insiderone.com/docs/api-rate-limits-1 .'
  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.\n\nEndpoint\n\nGET https://recommendation.api.useinsider.com/v2/chef\n\nQuery Parameters\n\nParameter\nSample Value\nDescription\nData Type\nRequired\n\npartnerName\nmybrand\nPartner Identifier, which is assigned by Insider One. You can use PartnerID as well.\nString\nYes\n\nlocale\nus_US\nLanguage or region of the site.\nString\nYes\n\nplatform\nweb\nIt is the requested platform. Its value can be web and app. Web comes by default.\nEnum\nNo\n\ncurrency\nUSD\nShows products with the specified currency.\nString\nNo\n\nuserId\ntestUser\nUser identifier, which is assigned by Insider One.\nString\nNo\n\nhp\nfalse, true or 0, 1\nMakes affinities affect the products of the response. The default is false.\nBoolean\nNo\n\ncategoryList\n[\"Tops\",\"Shirts\"]\nCategory filter of the products\n\nfilter\n\nSmart Recommender filtering. There can be more than one filter parameter.\nString\nNo\n\ndetails\ntrue\nAdds details to the products of the response.\nBoolean\nNo\n\nshuffle\nfalse\nShuffles the products of the response.\nBoolean\nNo\n\ngetGroupProducts\ntrue\nShows variant products under the products of the response.\nBoolean\nNo\n\ngroupProductsFields\n\nAdds these fields to the variant products’ details.\nString\nNo\n\nexcludeVariants\ntrue\nExclude variants from the response.\nBoolean\nNo\n\nexcludeViewDay\n30\nAfter how many days viewed products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nexcludeViewItem\n10\nHow many viewed products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nexcludePurchaseDay\n30\nAfter how many days purchased products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nexcludePurchaseItem\n10\nHow many purchased products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\ncountry\nItaly\nRequested country information\nString\nNo (Only for Location Based Top Sellers usage in Mixed Strategy)\n\ncity\nMilan\nRequested city information\nString\nNo (Only for Location Based Top Sellers usage in Mixed Strategy)\n\ndayLimit\n7\nThreshold last update day value for Publisher partners The default is 2 days.\nInteger\nNo\n\nulv\ntrue, false\nEnables User Last Visit to affect recommendation results\nBoolean\nNo\n\nSample Request\nThe 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.\n\nhttps://recommendation.api.useinsider.com/v2/chef?partnerName={PartnerName}&locale={Locale}\n\nSample Response\n{\n        \"success\": true,\n        \"total\": 16,\n        \"types\": {\n        \"mpop\": 14,\n        \"mvop\": 2\n        },\n        \"data\": [\n        \"ABC1234\",\n        \"ABC1243\",\n        \"ABC1234\",\n        \"ABC1235\",\n        \"ABC1237\",\n        \"ABC1230\",\n        \"ABC1263\",\n        \"ABC1209\",\n        \"ABC1256\",\n        \"CBA1234\",\n        \"CBA1233\",\n        \"CBA1236\",\n        \"CBA1239\",\n        \"CBA1221\",\n        \"CBA1209\",\n        \"CBA1247\"\n        ]\n        }\n\nFallback Algorithms\nThe 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).\n\nIt 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.\n\nEndpoint\n\nGET https://recommendation.api.useinsider.com/v2/complementary\n\nQuery Parameters\n\nParameter\nSample Value\nDescription\nData Type\nRequired\n\npartnerName\nmybrand\nPartner Identifier assigned by Insider One. You can use PartnerID as well.\nString\nYes\n\nlocale\nus_US\nLocale of requested product catalog\nString\nYes\n\nproductId\n1068\nThe reference product for which the complement is computed\nString\nYes\n\ncurrency\nUSD\nProduct currency. If no value is set, the default currency in your settings is used.\nString\nNo\n\nsize\n10\nResponse items. Valid values are 0 to 100.\nInteger\nNo\n\ncategoryList\n[“Clothes”]\nCategory filter of the products\nArray\nNo\n\nuserId\na1b2c3d4\nUser identifier; enables personalization boosts when provided\nString\nNo\n\nplatform\nweb\nRequested platform (default: web)\nEnum\nNo\n\ndetails\ntrue\nAdds details to the products of the response\nBoolean\nNo\n\nexcludeVariants\ntrue\nHides color/size variants of the same base product\nBoolean\nNo\n\nshuffle\nfalse\nShuffles the products of the response\nBoolean\nNo\n\nfilter\n[in_stock][=][true]\nRestricts results by fields such as price, brand, color, gender, in_stock, or category\nString\nNo\n\nhp\ntrue\nHyper-personalization flag. Re-ranks results using the shopper's attribute preferences\nBoolean\nNo\n\ngetGroupProducts\ntrue\nReturns all color/size variants grouped under each recommended product\nBoolean\nNo\n\ngroupProductsFields\nproduct_attributes.color,price\nComma-separated list of fields to include in the grouped variants; products missing any listed field are dropped\nString\nNo\n\ngetAllGroupProductsFields\ntrue\nReturns all variant fields without dropping products for missing fields; automatically enables getGroupProducts\nBoolean\nNo\n\nexcludeViewDay\n30\nDays before excluding previously viewed products\nInteger\nNo\n\nexcludeViewItem\n100\nNumber of viewed products to exclude\nInteger\nNo\n\nexcludePurchaseDay\n30\nDays before excluding previously purchased products\nInteger\nNo\n\nexcludePurchaseItem\n100\nNumber of purchased products to exclude\nInteger\nNo\n\nSample Request\nThe sample below shows a request to Complementary Products, the algorithm that suggests items frequently bought or viewed alongside the anchor product.\n\nhttps://recommendation.api.useinsider.com/v2/complementary?partnerName={PartnerName}&locale={Locale}&productId={ABC123}&size=10\n\nSample Response\n{\n  \"success\": true,\n  \"total\": 10,\n  \"types\": { \"cp\": 10 },\n  \"data\": [\n    \"649517_49890\",\n    \"568334_49053\",\n    \"639714_49677\"\n  ]\n}\n\nFallback Algorithms\nWhen Complementary Products results are insufficient, these algorithms fill the response:\n\nPurchased Together\n\nMost 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.\n\nEndpoint\n\nGET https://recommendation.api.useinsider.com/v2/highest-discounted\n\nQuery Parameters\n\nParameter\nSample Value\nDescription\nData Type\nRequired\n\npartnerName\nmybrand\nPartner Identifier assigned by Insider One. You can use PartnerID as well.\nString\nYes\n\nlocale\nus_US\nLocale of the requested product catalog\nString\nYes\n\nplatform\nweb\nRequested platform. Web comes by default.\nEnum\nNo\n\ncurrency\nUSD\nRequested currency of the products. If no value is set, the default currency in your settings is used.\nString\nYes\n\nuserId\na1b2c3d4\nUser identifier which is assigned by Insider One\nString\nNo\n\nhp\nfalse, true, or 1, 0\nMakes affinities affect products of the response. The default is false.\nBoolean\nNo (Can only be used with userId)\n\nsize\n50\nRequired number of items in response. Valid values are 0 to 100.\nInteger\nNo\n\ncategoryList\n[“Clothes”, “Skirts”]\nCategory filter of the products\nArray (of string)\nNo\n\nfilter\n\nSmart Recommender filtering. There can be more than one filter parameter.\nString\nNo\n\ndetails\ntrue\nAdds details to the products of the response\nBoolean\nNo\n\nshuffle\nfalse\nShuffles the products of the response\nBoolean\nNo\n\ngetGroupProducts\nfalse\nShows variant products under the products of the response\nBoolean\nNo\n\ngroupProductsFields\n\nAdds these fields to the variant products’ details\nString\nNo\n\nexcludeVariants\ntrue\nExclude variants from the response\nBoolean\nNo\n\nexcludeViewDay\n30\nAfter how many days viewed products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nexcludeViewItem\n10\nHow many viewed products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nexcludePurchaseDay\n30\nAfter how many days purchased products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nexcludePurchaseItem\n10\nHow many purchased products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nproductId\nABC123CBA\nCurrent product ID\nString\nNo\n\nIf you want to get top sellers products from the category or categories you want, specify either categoryList or category and subCategory.\n\nSample Request\nThe sample below displays a request for the Highest Discounted Products; the algorithm recommends products based on their discount ratios, prioritizing those with higher discounts.\n\nhttps://recommendation.api.useinsider.com/v2/highest-discounted?partnerName={Partner Name}&locale={Locale}&size=5¤cy={Currency}\n\nSample Response\n{\n        \"success\": true,\n        \"total\": 5,\n        \"types\": {\n        \"hdop\": 5\n        },\n        \"data\": [\n        \"AB76543\",\n        \"AB54321\",\n        \"YZ76543\",\n        \"AB49876\",\n        \"AB01234\"\n        ]\n        }\n\nFallback Algorithms\nIf the products from the Highest Discounted Products are not enough to fill the response data, some fallback algorithms below fill it:\n\nHighest 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.\n\nEndpoint\n\nGET https://recommendation.api.useinsider.com/v2/last-purchased-together\n\nQuery Parameters\n\nParameter\nSample Value\nDescription\nData Type\nRequired\n\npartnerName\n1000001\nPartner Identifier assigned by Insider One. You can use PartnerID as well.\nString\nYes\n\nlocale\nus_US\nLanguage or region of the site\nString\nYes\n\ncurrency\nUSD\nShows products with the specified currency\nString\nNo\n\nuserId\na1b2c3d4\nUser identifier that is assigned by Insider One\nString\nYes\n\nplatform\nweb\nRequested platform. Web comes by default.\nString\nNo\n\ndetails\ntrue\nAdds item details to the response\nBoolean\nNo\n\nhp\nfalse\nHyper-personalization activation\nBoolean\nNo\n\nsize\n50\nRequired number of items in response. The maximum allowed size is 100.\nInteger\nNo\n\nshuffle\nfalse\nShuffle the products in the response\nBoolean\nNo\n\nexcludeVariants\ntrue\nExclude 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.\nBoolean\nNo\n\nexcludePurchaseDay\n30\nExclude items the user purchased in X days\nInteger\nNo\n\nexcludeViewDay\n30\nExclude items the user viewed in X days\nInteger\nNo\n\nexcludePurchaseItem\n100\nThe number of purchased products to exclude\nInteger\nNo\n\nexcludeViewItem\n100\nThe number of viewed products to exclude\nInteger\nNo\n\nproductId\nABC123CBA\nCurrent product ID\nString\nNo\n\nfilter\n\nSmart Recommender filtering. There can be more than one filter parameter.\nString\nNo\n\ncategoryList\n[“Clothes”, “Skirts”]\nCategory filters of the product\nArray (of string)\nNo\n\ngetGroupProducts\ntrue, false\nShows variant products under the products of the response\nBoolean\nNo\n\ngroupProductsFields\nname, category\nAdds these fields to the variant products’ details\nString\nNo\n\ndayLimit\n7\nThreshold last update day value for Publisher partners. The default is 2 days.\nInteger\nNo\n\nSample Request\nThe sample below displays a request to Purchased with Last Purchased, one of Insider One’s personalized recommendation algorithms.\n\nhttps://recommendation.api.useinsider.com/v2/last=purchased-together?partnerName={PartnerName}&locale={Locale}&userId={UserId}\n\nSample Response\n{\n  \"success\": true,\n  \"total\": 10,\n  \"types\": {\n    \"lpt\": 10\n  },\n  \"data\": [\n    \"QAZ-7890\",\n    \"XYZ-1234\",\n    \"QAZ-7899\",\n    \"XYZ-1233\",\n    \"QAZ-7898\",\n    \"XYZ-1243\",\n    \"QAZ-7891\",\n    \"XYZ-1223\",\n    \"QAZ-7892\",\n    \"XYZ-1342\"\n  ]\n}\n\nFallback Algorithms\nBecause 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.\n\nEndpoint\n\nGET https://recommendation.api.useinsider.com/v2/manual-merchandising\n\nYou need to write Product IDs as comma-separated in the productId parameter, such as productId=ed061306,287a4a89,8f0db743,69de9b05\n\nQuery Parameters\n\nParameter\nSample Value\nDescription\nData Type\nRequired\n\npartnerName\nmybrand\nPartner Identifier assigned by Insider One. You can use PartnerID as well.\nString\nYes\n\nlocale\nus_US\nLocale of requested product catalog\nString\nYes\n\nplatform\nweb\nRequested platform. Web comes by default.\nEnum\nNo\n\ncurrency\nUSD\nRequested currency of the products. If no value is set, the default currency in your settings is used.\nString\nYes\n\nproductId\nABC1234\nThe ID of the product whose complementary is requested\nString\nYes\n\nuserId\ntestUser\nUser identifier which is assigned by Insider One\nString\nNo\n\nhp\nfalse, true or 0, 1\nMakes affinities affect products of the response. The default is false.\nBoolean\nNo (Can only be used with userId)\n\nsize\n50\nRequired number of items in response. Valid values are 0 to 100.\nInteger\nNo\n\nfilter\n\nSmart Recommender filtering. There can be more than one filter parameter.\nString\nNo\n\ndetails\ntrue\nAdds details to the products of the response\nBoolean\nNo\n\nshuffle\nfalse\nShuffles the products of the response\nBoolean\nNo\n\ngetGroupProducts\nfalse\nShows variant products under the products of the response\nBoolean\nNo\n\ngroupProductsFields\n\nAdds these fields to the variant products’ details\nString\nNo\n\nexcludeViewDay\n30\nAfter how many days viewed products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nexcludeViewItem\n10\nHow many viewed products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nexcludePurchaseDay\n30\nAfter how many days purchased products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nexcludePurchaseItem\n10\nHow many purchased products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nincludeOutOfStockItems\nFalse, true, 0, or 1\nBoolean flag to decide if out of stock products given in endpoint parameter should return in API response. The default is false.\nBoolean\nNo\n\nSample Request\nThe sample below displays a request to the Manual Merchandising algorithm:\n\nhttps://recommendation.api.useinsider.com/v2/manual-merchandising?partnerName={Partner Name}&locale={Locale}&productId=ABC12345,XYZ12345\n\nSample Response\n{\n    \"success\": true,\n    \"total\": 2,\n    \"types\": {\n        \"mm\": 2\n    },\n    \"data\": [\n        \"ABC12345\",\n        \"XYZ12345\"\n    ]\n}\n\nFallback Algorithms\nThere 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. It is a way to use different algorithms for each slot in the Recommendation Widget. The mixed strategy allows you to use multiple algorithms in a single recommendation widget on your website. It works best on the main and category pages.\n\nThe duplicated items are automatically removed by the Mixed Strategy algorithm.\n\nEndpoint\n\nGET https://recommendation.api.useinsider.com/v2/mixed\n\nQuery Parameters\n\nParameter\nSample Value\nDescription\nData Type\nRequired\n\npartnerName\nmybrand\nPartner Identifier assigned by Insider One. You can use PartnerID as well.\nString\nYes\n\nlocale\nus_US\nLocale of requested product catalog\nString\nYes\n\nplatform\nweb\nRequested platform. Web comes by default.\nEnum\nNo\n\ncurrency\nUSD\nRequested currency of the products. If no value is set, the default currency in your settings is used.\nString\nNo\n\nsize\n50\nRequired number of items in response. Valid values are 0 to 100.\nInteger\nNo\n\ncategoryList\n[“Clothes”, “Skirts”]\nCategory filter of the products\nArray (of string)\nNo\n\nfilter\n\nSmart Recommender filtering. There can be more than one filter parameter.\nString\nNo\n\ndetails\ntrue\nAdds details to the products of the response\nBoolean\nNo\n\nshuffle\nfalse\nShuffles the products of the response\nBoolean\nNo\n\ngetGroupProducts\nfalse\nShows variant products under the products of the response\nBoolean\nNo\n\ngroupProductsFields\n\nAdds these fields to the variant products’ details\nString\nNo\n\nexcludeVariants\ntrue\nExclude variants from the response\nBoolean\nNo\n\nstrategy\n[{\"recommendationType\":\"rvp\",\"size\":1}, {\"recommendationType\":\"ub\",\"size\":2}]\nList of strategies.\nString\nYes\n\nuserId\ntestUser\nUser ID\nString\nNo\n\nhp\nfalse, true, or 0, 1\nMakes affinities affect the products of the response. The default is false.\nBoolean\nNo\n\nexcludeViewDay\n30\nAfter how many days viewed products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nexcludeViewItem\n10\nHow many viewed products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nexcludePurchaseDay\n30\nAfter how many days purchased products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\nexcludePurchaseItem\n10\nHow many purchased products should be excluded. The default is -1.\nInteger\nNo (Can only be used with userId)\n\ncountry\nGermany\nRequested country information\nString\nNo (Only for Location Based Top Sellers usage in Mixed Strategy)\n\ncity\nHamburg\nRequested city information\nString\nNo (Only for Location Based Top Sellers usage in Mixed Strategy)\n\ndayLimit\n7\nThreshold last update day value for Publisher partners (The default is 2 days.)\nInteger\nNo\n\nulv\ntrue, false\nEnables User Last Visit to affect the recommendation results\nBoolean\nNo\n\nYou need to add the necessary query parameters for the strategy or strategies you are using.\n\nStrategy\nStrategy is used to specify the desired recommendation types and sizes. Strategies are given within an array. Each strategy is an object that contains the keys recommendationType and size. recommendationType indicates the type of recommendation required, while size specifies the quantity needed.\n\n[\n    {\n        \"recommendationType\": \"ub\",\n        \"size\": 2\n    },\n    {\n        \"recommendationType\": \"btb\",\n        \"size\": 2\n    },\n    ...\n]\n\nList of Strategies\n\nAlgorithm\nAbbreviation\n\nChef\nchef\n\nComplementary Products\ncp\n\nHighest Discounted\nhdop\n\nHighest Discounted of Category\nhdoc\n\nLocation Based Top Sellers\nmpol\n\nManual Merchandising\nmm\n\nMost Popular\nmvop\n\nMost Popular of Category\nmvoc\n\nMost Valuable Products\nmvpop\n\nMost Valuable Products of Category\nmvpoc\n\nNew Arrivals\nnaop\n\nNew Arrivals of the Category\nnaoc\n\nViewed Together\nvtv\n\nPurchased Together\nbtb\n\nPurchased with Last Purchased\nlpt\n\nSubstitute Products\nsp\n\nTop Sellers\nmpop\n\nTop Sellers of Category\nmpoc\n\nTrending Products\ntpop\n\nTrending Products of Category\ntpoc\n\nUser Based\nub\n\nViewed Together\nvtv\n\nSample Request\nThe sample below displays a request to the Mixed Strategy algorithm:\n\nhttps://recommendation.api.useinsider.com/v2/mixed?locale={Locale}&partnerName={PartnerName}&strategy=[{\"recommendationType\":\"hdop\",\"size\":2}]\n\nSample Response\n{\n    \"success\": true,\n    \"total\": 2,\n    \"types\": {\n        \"hdop\": 2\n    },\n    \"data\": [\n        \"XYZ-987789\",\n        \"ABC-123321\"\n    ]\n}\n\nFallback Algorithms\nFallback algorithms are determined by your strategy selections."
      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. It generates recommendations based on the page view counts during the last 30 days. The Most Popular Items algorithm works best on main, category, and product pages.\n\nEndpoint\nGET https://recommendation.api.useinsider.com/v2/most-popular\n\nQuery Parameters\n\nParameter\nSample Value\nDescription\nData Type\nRequired\n\npartnerName\nmybrand\nPartner Identifier assigned by Insider One. You can use PartnerID as well.\nString\nYes\n\nlocale\nus_US\nLocale of requested product catalog\nString\nYes\n\nplatform\nweb\nRequested platform. Web comes by default.\nEnum\nNo\n\ncurrency\nUSD\nRequested currency of the products. If no value is set, the default currency in your settings is used.\nString\nNo\n\nsize\n50\nRequired number of items in response. Valid values are 0 to 100.\nInteger\nNo\n\ncategoryList\n[“Clothes”, “Skirts”]\nCategory filter of the products\nArray (of string)\nNo\n\nfilter\n\nSmart Recommender filtering. There can be more than one filter parameter.\nString\nNo\n\ndetails\ntrue\nAdds details to the products of the response\nBoolean\nNo\n\nshuffle\nfalse\nShuffles the products of the response\nBoolean\nNo\n\ngetGroupProducts\nfalse\nShows variant products under the products of the response\nBoolean\nNo\n\ngroupProductsFields\n\nAdds these fields to the details of variant products\nString\nNo\n\nexcludeVariants\ntrue\nExclude variants from the response.\nBoolean\nNo\n\nuserId\na1b2c3d4\nUser identifier, which is assigned by Insider One\nString\nNo\n\nexcludeViewDay\n30\nAfter how many days should viewed products be excluded\nInteger\nNo (Can be used only with userId)\n\nexcludeViewItem\n100\nHow many viewed products should be excluded\nInteger\nNo (Can be used only with userId)\n\nexcludePurchaseDay\n30\nAfter how many days should purchased products be excluded\nInteger\nNo (Can be used only with userId)\n\nexcludePurchaseItem\n100\nHow many purchased products should be excluded\nInteger\nNo (Can be used only with userId)\n\nhp\nfalse\nMakes affinities affect products of the response\nBoolean\nNo\n\nproductId\nABC123CBA\nCurrent product ID\nString\nNo\n\nAlgorithm Customization\nThe Most Popular Items algorithm also provides users with product recommendations based on their popularity within categories. To obtain category-based most popular products, the API endpoint should include the categoryList parameter with valid category values from the Product Catalog.\n\nVariant Name\nCondition\nParameter(s)\n\nMost Popular Items of Partner\nNo category filter\nDefault (no categoryList)\n\nMost Popular Items of Category\nCategory filter provided\ncategoryList=[category1, category2, ...]\n\nWhen categoryList is provided, recommendations are filtered to show only the Most Popular products within the specified categories. Recommendations served in the API response will be abbreviated as mvoc for Most Popular Items of Category recommendations.\n\nSample Request\nThe sample below displays a request to Most Popular Items, an algorithm that recommends products with the highest overall engagement based on page views.\n\nhttps://recommendation.api.useinsider.com/v2/most-popular?locale={Locale}&partnerName={PartnerName}\n\nSample Response\n{\n    \"success\": true,\n    \"total\": 1,\n    \"types\": {\n        \"mvop\": 1\n    },\n    \"data\": [\n{\n            \"image_url\": \"test.image_url.com\",\n            \"name\": \"Original Air-dried Beef recipe for dogs\",\n            \"item_id\": \"46177313784082\",\n            \"url\": \"test.url.com\",\n            \"description\": \"Having access to lush fields of grass year-round makes New Zealand free-range, grass-fed beef among the best in the world.\",\n            \"in_stock\": 1,\n            \"price\": {\n                \"USD\": 29.58\n            },\n            \"groupcode\": \"8528988209426\",\n            \"locale\": \"en_US\",\n            \"product_attributes\": {\n                \"activation_date\": \"2023-08-11\",\n                \"shopify_tag\": [\n                    \"air-dried\",\n                    \"beef\",\n                    \"dog\"\n                ]\n            },\n            \"stock_count\": 99,\n            \"category\": [\n                \"Dog Food\",\n                \"Pets Collection\"\n            ],\n            \"discount\": {\n                \"USD\": 0.0\n            },\n            \"original_price\": {\n                \"USD\": 29.58\n            }\n        }\n    ]\n}\n\nSample Request for Most Popular of Category\nhttps://recommendation.api.useinsider.com/v2/most-popular?locale={Locale}&partnerName={PartnerName}&categoryList=[“Dog Food”]\n\nSample Response\n{\n    \"success\": true,\n    \"total\": 1,\n    \"types\": {\n        \"mvoc\": 1\n    },\n    \"data\": [\n{\n            \"image_url\": \"test.image_url.com\",\n            \"name\": \"Original Air-dried Beef recipe for dogs\",\n            \"item_id\": \"46177313784082\",\n            \"url\": \"test.url.com\",\n            \"description\": \"Having access to lush fields of grass year-round makes New Zealand free-range, grass-fed beef among the best in the world.\",\n            \"in_stock\": 1,\n            \"price\": {\n                \"USD\": 29.58\n            },\n            \"groupcode\": \"8528988209426\",\n            \"locale\": \"en_US\",\n            \"product_attributes\": {\n                \"activation_date\": \"2023-08-11\",\n                \"shopify_tag\": [\n                    \"air-dried\",\n                    \"beef\",\n                    \"dog\"\n                ]\n            },\n            \"stock_count\": 99,\n            \"category\": [\n                \"Dog Food\",\n                \"Pets Collection\"\n            ],\n            \"discount\": {\n                \"USD\": 0.0\n            },\n            \"original_price\": {\n                \"USD\": 29.58\n            }\n        }\n    ]\n}\n\nFallback Algorithms\nIf the products come from Most Popular Items are not enough to fill the response data, some fallback algorithms below fill it:\n\nMost viewed items of the category, including the rightmost item in the categoryList"
      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.\n\nEndpoint\n\nGET https://recommendation.api.useinsider.com/v2/most-valuable\n\nQuery Parameters\n\nParameter\nSample Value\nDescription\nData Type\nRequired\n\npartnerName\nmybrand\nPartner Identifier assigned by Insider One. You can use PartnerID as well.\nString\nYes\n\nlocale\nus_US\nLocale of the requested product catalog\nString\nYes\n\nplatform\nweb\nRequested platform. Web comes by default.\nEnum\nNo\n\ncurrency\nUSD\nRequested currency of the products. If no value is set, the default currency in your settings is used.\nString\nNo\n\nsize\n50\nRequired number of items in response. Valid values are 0 to 100.\nInteger\nNo\n\ncategoryList\n[“Clothes”, “Skirts”]\nCategory filter of the products\nArray (of string)\nNo\n\nfilter\n\nSmart Recommender filtering. There can be more than one filter parameter.\nString\nNo\n\ndetails\ntrue\nAdds details to the products of the response.\nBoolean\nNo\n\nshuffle\nfalse\nShuffles the products of the response.\nBoolean\nNo\n\ngetGroupProducts\nfalse\nShows variant products under the products of the response\nBoolean\nNo\n\ngroupProductsFields\n\nAdds these fields to the variant prod

# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/insider/refs/heads/main/openapi/insider-algorithm-descriptions-api-openapi.yml