Insider Recommendations API

openapi: 3.2.0
info:
  title: Insider One Recommendation Recommendations 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: Recommendations
paths:
  /v2/{algorithm-name}:
    get:
      operationId: getRecommendations
      summary: Get Recommendations
      tags:
      - Recommendations
      description: "The Recommendation API (SR-API) is a RESTful service for programmatically retrieving personalized product suggestions. It serves as the interface to Insider One’s recommendation engine, utilizing machine learning models, real-time user behavior analysis, and product affinity data to return structured item sets.\n\nEndpoint\nThe Recommendation API follows a standard RESTful pattern:\n\nGET https://recommendation.api.useinsider.com/v2/{algorithm-name}\n\n{algorithm-name} is the unique identifier for the recommendation logic to be executed.\n\nExamples:\n\n/v2/most-popular - Most viewed products\n\n/v2/user-based - Personalized user recommendations\n\n/v2/purchased-together - Frequently bought together items\n\nRefer to Algorithm Descriptions for the full list.\n\nBefore making your first request, you'll need:\n\nAll requests require your API token in the request header.\n\nPartner ID/Name - Your store identifier\n\nLocale - Language and region code used for recommendation context (e.g., en_US, fr_FR)\n\nCurrency - Currency code (e.g., USD, EUR)\n\nAlgorithm Abbreviations\nEach algorithm has a short abbreviation used in response payloads:\n\nmvop = Most Popular Items\n\nub = User Based\n\nbtb = Purchased Together\n\nchef = Chef (automated strategy selector)\n\nRefer to the Algorithm Descriptions for the complete list.\n\nQuery Parameters\nAll endpoints support common parameters:\n\nParameter\nPurpose\nType\nRequired\n\npartnerName\nYour store identifier\nString\nYes\n\nlocale\nLanguage/region (e.g., en_US)\nString\nYes\n\ncurrency\nCurrency code (e.g., USD)\nString\nYes\n\nuserId\nUser identifier for personalization\nString\nNo\n\ncategoryList\nFilter by product categories\nArray\nNo\n\nfilter\nAdvanced filtering (see Filtering Guide)\nString\nNo\n\nsize\nNumber of products (0-100)\nInteger\nNo\n\ndetails\nInclude full product information\nBoolean\nNo\n\nSample Request\ncurl -X GET \"https://recommendation.api.useinsider.com/v2/most-popular?partnerName=dataforceapi&locale=tr_TR&size=1&details=true\" \\\n     -H \"X-Auth-Token: YOUR_API_TOKEN\"\n\nconst apiToken = 'YOUR_API_TOKEN';\n                    const endpoint = 'https://recommendation.api.useinsider.com/v2/most-popular';\n                    const params = {\n                    partnerName: 'yourPartnerName',\n                    locale: 'tr_TR',\n                    size: 1,\n                    details: true\n                    };\n                    const queryString = new URLSearchParams(params).toString();\n                    fetch(`${endpoint}?${queryString}`, {\n                    method: 'GET',\n                    headers: {\n                    'X-Auth-Token': apiToken\n                    }\n                    })\n                    .then(response => response.json())\n\nimport requests\n                    api_token = 'YOUR_API_TOKEN'\n                    endpoint = 'https://recommendation.api.useinsider.com/v2/most-popular'\n                    params = {\n                    'partnerName': 'yourPartnerName',\n                    'locale': 'tr_TR',\n                    'size': 1,\n                    'details': True\n                    }\n                    headers = {\n                    'X-Auth-Token': api_token\n                    }\n                    response = requests.get(endpoint, params=params, headers=headers)\n                    data = response.json()\n                    print(data)\n\nSample Response\nResponses follow a consistent JSON structure:\n\n{\n        \"success\": true,\n        \"total\": 10,\n        \"types\": {\n        \"mvop\": 10\n        },\n        \"data\": [\"productId1\", \"productId2\", ...]\n        }\n\n<p >With details=true, the data array contains full product objects including pricing, images, categories, and attributes.</p> \n\n200 / Success-OK\nA successful response looks like this:\n\n{\n        \"success\": true,\n        \"total\": 1,\n        \"types\": {\n        \"mvop\": 1\n        },\n        \"data\": [\"SKU-DK-0011\"]\n        }\n\nField\nMeaning\n\nsuccess\nBoolean indicating if the request succeeded\n\ntotal\nNumber of products returned\n\ntypes\nAlgorithm(s) used (mvop = Most Popular of Partner)\n\ndata\nArray of product IDs\n\nGetting Product Details\nBy default, the API returns only product IDs. To get full product information (images, prices, descriptions), add details=true.\n\ncurl -X GET \"https://recommendation.api.useinsider.com/v2/most-popular?partnerName=yourpartnername&locale=tr_TR&size=1&details=true\" \\\n     -H \"X-Auth-Token: YOUR_API_TOKEN\"\n\nconst params = {\n                    partnerName: 'yourpartnername',\n                    locale: 'tr_TR',\n                    size: 1,\n                    details: true\n                    };\n\nparams = {\n                    'partnerName': 'yourpartnername',\n                    'locale': 'tr_TR',\n                    'size': 1,\n                    'details': True\n                    }\n\nResponse with details=true includes:\n\nimage_url - Product image\n\nname - Product name\n\nprice - Product pricing (by currency)\n\ncategory - Product categories\n\ndiscount - Discount information\n\nin_stock - Stock status\n\nHere is a full example with details=true:\n\n{\n        \"success\": true,\n        \"total\": 1,\n        \"types\": {\n        \"mvop\": 1\n        },\n        \"data\": [\n        {\n        \"item_id\": \"SKU-HA-0011\",\n        \"name\": \"Hummingbird Decorative Cushion\",\n        \"locale\": \"en_US\",\n        \"image_url\": \"https://cdn.demo-shop.com/images/home-accessories/hummingbird-cushion-45x45.jpg\",\n        \"url\": \"https://www.demo-shop.com/en/home-accessories/hummingbird-decorative-cushion?ins_sr=eyJwcm9kdWN0SWQiOiJTS1UtSEEtMDAxMSJ9\",\n        \"in_stock\": 1,\n        \"price\": {\n        \"USD\": 24.99\n        },\n        \"original_price\": {\n        \"USD\": 29.99\n        },\n        \"discount\": {\n        \"USD\": 5.0\n        },\n        \"category\": [\n        \"Home Accessories\",\n        \"Decorative Cushions\"\n        ],\n        \"description\": \"Soft cotton decorative cushion with hummingbird pattern. Ideal for living rooms and bedrooms.\",\n        \"brand\": \"Demo Home\",\n        \"color\": \"Multicolor\",\n        \"size\": \"45x45 cm\",\n        \"tags\": [\n        \"cushion\",\n        \"home-decor\",\n        \"living-room\"\n        ],\n        \"material_type\": \"Cotton\",\n        \"washable\": \"Yes\",\n        \"room\": \"Living Room\"\n        }\n        ]\n        }\n\nThe following table demonstrates the status codes and response types from the Recommendation API. The table lists Status Codes, their descriptions, and scenarios that you can receive these status codes.\n\nStatus Code\nStatus Code Scenarios\n\n200 - Success\nSuccessful API requests receive responses with 200 status code.\n\n400 - Bad Request\nUnsuccessful API requests receive responses with 400 status code.API calls with missing endpoint parameters receive this status code.\n\n403 - Forbidden\nUnauthorized API requests receive responses with 403 status codeAPI calls that result with unsuccessful Origin/CORS Validation receive this status code.\n\n422 - Unprocessible Content\nAPI calls that have missing dynamic filter content receive this status code.Refer to the Filtering Products documentation for further details.\n\n429 - Too Many Requests\nThrottled API requests receive responses with 429 status code.\n\n200 / Success-OK\nSuccessful Recommendation API requests receive an API endpoint that contains the following fields:\n\nsuccess field that denotes the success of the API response,\n\ntotal field displays the number of recommendations returned from the API response,\n\ntypes field that lists recommendation algorithm types that returned from the endpoint,\n\ndata field lists the recommendations and their details\n\nFollowing is a successful Recommendation API request and its example response:\n\nSample Request\nhttps://recommendationv2.api.useinsider.com/v2/most-popular?details=true&partnerName=yourPartnerName&locale=en_US¤cy=USD&size=1\n\nSample Response\n{\n    \"success\": true,\n    \"total\": 1,\n    \"types\": {\n        \"mvop\": 1\n    },\n    \"data\": [\n        {\n            \"image_url\": \"http://insiderone.com/img/p/1/3/13.jpg\",\n            \"name\": \"Hummingbird cushion\",\n            \"item_id\": \"11\",\n            \"url\": \"https://insiderone.com/home-accessories/11-hummingbird-cushion.html#ins_sr=eyJwcm9kdWN0SWQiOiIxMSJ9\",\n            \"description\": \"Hummingbird cushion in category Home Accessories\",\n            \"in_stock\": 1,\n            \"price\": {\n                \"USD\": 0.57\n            },\n            \"locale\": \"en_US\",\n            \"product_attributes\": {\n                \"test\": \"productTest\",\n                \"testattributes\": \"productTest\"\n            },\n            \"category\": [\n                \"Home Accessories\"\n            ],\n            \"discount\": {\n                \"USD\": 0.0\n            },\n            \"original_price\": {\n                \"USD\": 0.57\n            }\n        }\n    ]\n}\n\n400 / Bad Request\nIn the following scenarios, the Recommendation API returns responses with a 400 status code:\n\nMissing required endpoint parameters\n\nMissing required endpoint parameter values\n\nWrong usage of endpoint parameters\n\nFollowing API requests and responses demonstrate examples of these scenarios.\n\nSample Request 1\nThe partnerName parameter is missing in the request below:\n\nhttps://recommendationv2.api.useinsider.com/v2/most-popular?details=true¤cy=USD&locale=en_US\n\nSample Response 1\n{\n    \"success\": false,\n    \"message\": \"Missing parameter: partnerName\",\n    \"data\": []\n}\n\nSample Request 2\nThe locale value is missing in the request below:\n\nhttps://recommendationv2.api.useinsider.com/v2/most-popular?details=true¤cy=USD&locale=&partnerName=yourPartnerName\n\nSample Response 2\n{\n    \"success\": false,\n    \"message\": \"Locale is invalid.\",\n    \"data\": []\n}\n\n403 / Forbidden\nThe Recommendation API performs sender origin validation for partners that enable the Origin/CORS Validation feature. When the feature is enabled, the Recommendation API only provides successful recommendation content to callers from the allowed domains. Requests from domains that are not listed as allowed domains will receive failures with a 403 status code.\n\nFollowing is the Recommendation API response for unsuccessful validations:\n\n{\n    \"success\": false,\n    \"message\": \"Origin validation error.\",\n    \"data\": []\n}\n\n422 / Unprocessible Content\nThis endpoint response status code is often received when the partner page that hosts the recommendation campaign cannot provide the details that the Recommendation API endpoint needs to use.\n\nAs an example scenario;\n\nYou create and activate a Web Smart Recommender campaign on Product Pages that has Dynamic Filtering usage on the color field.\n\nIn Dynamic Filtering, the attribute values of fields used in filters are fetched from the Recommendation API.\n\nThus, web clients are not informed whether the requested attribute is present for the current product.\n\nIn cases where the attribute value that is used in the Dynamic Filter is missing, the Recommendation API cannot perform the Dynamic Filter.\n\nThe API returns with a 422 status code for those cases.\n\nSample Request\nhttps://recommendationv2.api.useinsider.com/v2/most-popular?details=true&filter=([color][=][${value}])¤cy=TRY&locale=tr_TR&partnerName=yourPartnerName&productId=11\n\nSample Response\nThe color attribute was missing for the given item with ID “11”. When this attribute is requested with dynamic filtering, the Recommendation API responds with a 422 status code (denoting that an unprocessible content is present)\n\n{\n    \"success\": false,\n    \"message\": \"The field 'color' in dynamic filter was not found in the product.\",\n    \"data\": []\n}\n\n429 / Too Many Requests\nWhen you exceed the rate limit, the Recommendation API will temporarily throttle your requests. Rate limits are calculated using a rolling one-minute window, so if you're throttled, you'll regain access once the current window resets (at most one minute).\n\n{\n    \"success\": false,\n    \"message\": \"Rate exceeded.\",\n    \"data\": []\n}\n\nFiltering Recommendation Responses\nFiltering allows you to refine recommendation results to match your users' needs and preferences. Common use cases include:\n\nExclude already-viewed products - Don't recommend products the user has seen\n\nPrice range filtering - Show only products within budget\n\nCategory/brand filtering - Focus on specific product types\n\nStock filtering - Only recommend in-stock items\n\nAttribute filtering - Filter by custom product attributes (color, size, rating, etc.)\n\nThis increases relevance, improves user experience, and boosts conversion rates.\n\nBasic Syntax\nhttps://recommendation.api.useinsider.com/v2/{algorithm}?...\\&filter=[{field}][{operator}][{value}]\n\nHere is an example with a single filter that returns  products with prices greater than 100 USD:\n\n?filter=[price.USD][>][100]\n\nMultiple Filters\nYou can pass multiple filter parameters to combine conditions. Each condition is chained together via an asterisk (*).\n\nSyntax\n?filter=[field1][operator1][value1]*[field2][operator2][value2]\n\nHow Multiple Filters work\nMultiple filters are combined with AND logic - products must match ALL conditions to be included.\n\nExample 1: Exclude current product + filter by category\n?filter=[item_id][!=][PRODUCT_ID]*[category][~][Shoes]\n\nThis filter returns products that are NOT PRODUCT_ID AND contain \"Shoes\" in the category.\n\nExample 2: Price range + in stock\n?filter=[price.USD][>][50]*[price.USD][<][200]*[in_stock][=][1]\n\nThis filter returns products between $50-$200 AND in stock.\n\nOperator Reference\n\nOperator Name\nSymbol\nAlias\nDescription\nExample\n\nEqual To\n=\nis\nExact match on field value\n[color][=][Blue] or [brand][=][Niki]\n\nNot Equal To\n!=\nnis\nExcludes products with matching field value\n[color][!=][Red] (exclude red products)\n\nGreater Than\n>\ngt\nField value greater than the specified value\n[price.USD][>][100] or [rating][>][3.5]\n\nGreater Than or Equal\n>=\ngte\nField value greater than or equal to the specified value\n[price.EUR][>=][150] or [rating][>=][4]\n\nLess Than\n<\nlt\nField value less than the specified value\n[price.EUR][<][150] or [stock_count][<][5]\n\nLess Than or Equal\n<=\nlte\nField value less than or equal to the specified value\n[price.EUR][<=][150] or [created_at][<=][now-7d]\n\nContains\n~\nctn\nField contains the specified value (text search)\n[category][~][Shoes] or [name][~][Niki Air]\n\nDoes Not Contain\n!~\nnctn\nField does not contain the specified value\n[category][!~][Clearance]\n\nBetween\n><\nbtw\nField value falls within a range. Format: [field][><][lower_bound:upper_bound]\n[price.USD][><][50:200]\n\nNot Between\n>!<\nnbtw\nField value falls outside a range\n[price.USD][>!<][50:200] (exclude $50-$200 range)\n\nExists\n?\nxst\nCheck if a field exists (value=1) or does not exist (value=0)\n[price.USD][?][1] (products have USD price)\n\nDate Field Values\nInsider One is designed to parse every filter value provided for date fields. If a simplified date expression fails to parse, the system will use it as a raw literal value. This allows you to use literal dates (e.g., \"2022-09-30 15:45:00\") directly in your date filters.\n\nThe date fields available for filtering are: created_at and modified_at.\n\nOperator Compatibility\nDate fields are supported by every operator except for Between (><) and Not Between (>!<). This limitation is due to the Between operator using a colon (:) to separate the lower and upper bounds, which conflicts with the colon present in standard date/time formats (e.g., 2022-09-30 15:45:00).\n\nThe most appropriate operators for date fields are:\n\nAfter (>)\n\nBefore (<)\n\nIs (=)\n\nIs Not (!=)\n\nRelative Date Filtering\nDate filters also support relative unit values, allowing you to easily filter based on time relative to the current moment (now).\n\nAnchor: now\n\nUnits: w (week), d (day), h (hour)\n\nModifiers: Use + to add units or - to subtract units.\n\nYou can see the examples below:\n\nScenario\nFilter Expression\n\nGet products that were created last week\n[created_at][>][now-1w]\n\nGet products created up to 2 days ago\n[created_at][<=][now-2d]\n\nMultiple Value Filtering (In / Not-In Filter Behavior)\nMatch fields against multiple values by separating them with:\n\n||\n\nSupported by all operators except between and not between.\n\nExamples:\n\nGet products from multiple brands:\n\n?filter=[brand][=][Niki||Abiba||Pamu]\n\nExclude multiple colors:\n\n?filter=[color][!=][Red||Green||Blue]\n\nGet products with categories containing any of these terms:\n\n?filter=[category][~][Shoes||Boots||Sneakers]\n\nAdvanced Filtering with AND/OR\nCombine multiple filters using logical operators within a single filter parameter.\n\nAnd (*) = both conditions must be true\n\nOr (|) = either condition can be true\n\nExamples\n\nAND Example: Price range AND brand\n\n?filter=([price.USD][>][100]*[brand][=][Niki]) \n\nOR Example: Multiple categories\n\n?filter=([category][~][Shoes]|[category][~][Boots])\n\nComplex: (A AND B) OR C\n\nGet products that are either (cheap AND in stock) OR highly rated:\n\n?filter=((price.USD][<][50]*[in_stock][=][1])|[rating][>=][5])\n\nYou can also use multiple parameters to achieve AND logic more simply:\n\n?filter=[price.USD][<][50]&filter=[in_stock][=][1]&filter=[rating][>=][5]\n\nThis is often clearer than using complex parentheses.\n\nDynamic Filters\nUse ${value} to reference the source product's field value in your filter. The expression is computed at request time using the actual product data.\n\nSupported Expressions\n\n${value} - Use the product's field value as-is\n\n${value*1.2} - Multiply by 1.2 (20% increase)\n\n${value*0.8} - Multiply by 0.8 (20% decrease)\n\n${value*0.8}:${value*1.3} - Range with dynamic bounds\n\nExamples\n\nMatch the product's category dynamically:\n\n?categoryList=${value}&productId=PRODUCT_ID\n\nIf the product has a category \"Shoes\", recommendations are filtered to \"Shoes\" only.\n\nShow products in a similar price range (±30%):\n\n?productId=PRODUCT_ID&filter=[price.EUR][><][${value}:${value*1.3}]\n\nIf the product costs €100, it shows products priced €100-€130.\n\nFilter Validation Errors\nWhen filters are invalid, the API returns specific error messages with HTTP status codes:\n\nFormat & Syntax Errors (400)\n\nError\nCause\n\n\"Filter is not in correct format.\"\nMissing brackets, unmatched parentheses, invalid syntax\n\n\"Depth of nested filters is greater than 4.\"\nToo many nesting levels: ((((filter))))\n\n\"Number of filters is greater than 40.\"\nToo many filter conditions total\n\nField Errors (400 or 422)\n\nError\nHTTP\nCause\n\n\"Entered field name is invalid.\"\n400\nField doesn't exist in product data\n\n\"The field '%s' in dynamic filter was not found in the product.\"\n422\nField missing in source product (dynamic filters only)\n\n\"Field $$$ is not filterable product attribute.\"\n400\nField marked non-filterable in configuration\n\nOperator Errors (400)\n\nError\nCause\n\n\"operator field is invalid.\"\nUnknown operator (use: =, !=, >, <, >=, <=, ~, !~, ><, >!<, ?)\n\n\"For the $$$ field, operator field is not valid by field type.\"\nOperator incompatible with field type (e.g., ~ on numeric field)\n\n\"Operator $$$ is not allowed for dynamic filters.\"\nEXIST/EXIST_ALIAS not allowed with ${value}\n\nValue Errors (400 or 422)\n\nError\nHTTP\nCause\n\n\"For the $$$ field, entered value is empty.\"\n422\nBlank or null value\n\n\"For the $$$ field, value length is invalid.\"\n400\nExceeds limits (100 chars for text search, 340 for others)\n\n\"Value for the field $$$ is invalid.\"\n400\nInvalid range format (use lower:upper for >< operator)\n\n\"For the $$$ field, value type is invalid.\"\n400\nType mismatch (non-numeric on numeric field)\n\nField-Specific Validations (400)\n\nField\nError\nCause\n\nin_stock\n\"Value is invalid for in_stock filter...\"\n0 or 1 only\n\nDynamic Filter Errors (400)\n\nError\nCause\n\n\"Parameters productId and locale must be provided when dynamic value is used.\"\nUsing ${value} without providing productId or locale\n\n\"Product not found\"\nSpecified productId doesn't exist\n\nLimitations\n\nConstraint\nLimit\nNotes\n\nFilter depth\n4 levels\nMaximum nesting depth for parentheses\n\nTotal filters\n40 filters\nTotal number of filter conditions in one request\n\nN-gram value length\n100 characters\nFor text search on item_id, name, image_url\n\nOther field value length\n340 characters\nFor text search on other fields\n\nPersonalized Recommendation Features\nThe Recommendation API provides a range of personalization capabilities that tailor product recommendations to individual users. By leveraging user behavior, such as browsing history, purchase activity, and real-time interactions, the API delivers more relevant product suggestions that increase engagement and conversion rates.\n\nTo enable personalization, you must include the Insider ID in your Recommendation API requests. This allows the system to associate incoming requests with existing user profiles and apply behavior-driven logic.\n\nCurrently, the Recommendation API supports the following personalization features:\n\nPersonalized Recommendation Algorithms\nThe following recommendation algorithms inherently deliver personalized product suggestions based on user behavior and interaction data.\n\nUser-Based Recommendations\n\nGenerate personalized recommendations by analyzing a user’s historical interactions and the behavior patterns of similar users.\n\nReal-Time User Engagement Recommendations\n\nProvide real-time personalized suggestions based on the user’s current session activity and live interactions.\n\nRecently Viewed Products\n\nRecommend products based on the user’s most recent product page views, helping reinforce recent browsing intent.\n\nPurchased with Last Purchased\n\nSuggest products that are frequently purchased together with the user’s most recent purchase, supporting effective cross-sell scenarios.\n\nThese algorithms leverage both historical and real-time data to ensure recommendations remain relevant, timely, and aligned with individual user preferences.\n\nPersonalization with the User’s Last Visited Item\nThe Recommendation API can personalize results using the last product page a user visited. This behavior applies to both User-Based Recommendations and Real-Time User Engagement algorithms.\n\nWhen the API does not have sufficient user-level data to generate a fully personalized recommendation, it automatically falls back to Viewed Together recommendations based on the user’s most recently viewed product.\n\nThis fallback mechanism ensures that recommendations remain relevant and context-aware, even when historical user data is limited.\n\nPersonalization with Users Recent Interactions\nThe Recommendation API can automatically exclude products a user has already interacted with, so they won't see recommendations for items they've viewed, purchased, or otherwise engaged with.\n\nUse the following parameters to enable these exclusions:\n\nAPI Endpoint Parameter\nDescription\n\nexcludeViewItem\nExcludes the last X Product Visits of the user from the API response\n\nexcludeViewDay\nExcludes Product Page views of the user in the last X days from the API response\n\nexcludePurchaseItem\nExcludes the last X Product Purchases of the user from the API response\n\nexcludePurchaseDay\nExcludes Product Purchases of the user in the last X days from the API response\n\nThe following Recommendation API requests illustrate these personalization features:\n\nThe request below instructs the Recommendation API to exclude the last ten products the user viewed in Product Detail pages from the API response:\n\nhttps://recommendationv2.api.useinsider.com/v2/most-popular?details=true¤cy=TRY&locale=tr_TR&partnerName=dataforceapi&userId=testUser&excludeViewItem=10\n\nThe request below instructs the Recommendation API to exclude the products that the user purchased in the last three days.\n\nhttps://recommendationv2.api.useinsider.com/v2/most-popular?details=true¤cy=TRY&locale=tr_TR&partnerName=dataforceapi&userId=testUser&excludePurchaseDay=3\n\nAttribute Affinity\nAttribute affinity scores represent a user’s preference for specific product attributes based on their interaction behavior, including product views, add-to-cart actions, and purchases. Purchases carry a higher weight than views, as they indicate stronger intent. Affinity scores are normalized by a user’s total activity. As a result, a user with a high purchase-to-view ratio demonstrates a stronger affinity than a user who browses frequently but converts rarely.\n\nThe Recommendation API uses attribute affinity to personalize product recommendations according to each user’s demonstrated interests. Affinity data is refreshed daily, ensuring recommendations reflect recent and relevant user behavior.\n\nWithin the Recommendation API, the hp endpoint parameter controls whether the Attribute Affinity feature is applied. When enabled, the API incorporates a user’s attribute affinity scores into the recommendation logic, prioritizing products that align with the user’s strongest preferences.\n\nThe following Recommendation API request demonstrates how the Attribute Affinity feature is applied when the hp parameter is enabled:\n\nhttps://recommendationv2.api.useinsider.com/v2/most-popular?details=true¤cy=TRY&locale=tr_TR&partnerName=yourPartnerName&userId=testUser&hp=1\n\nAPI Rate Limits\nThe rate limit for direct API calls is set to 1000 calls per minute, applied across all endpoints of the Recommendation API. Exceeding this rate limit causes additional requests to return 429 status codes.\n\n<p >If your technical architecture requires a higher throughput, contact the Insider One team.</p> \n\nBest Practices for Recommendation API\nCategory List Format\nWhen filtering by categories, pass categoryList as a URL-encoded JSON array:\n\ncategoryList=[\"shoes\",\"boots\"]\n\nIn cURL, encode the brackets properly:\n\n?categoryList=[\"shoes\",\"boots\"]\n\nHyperpersonalization (hp)\nEnable hyperpersonalization by adding hp=1 or hp=true:\n\n?userId=user123&hp=1\n\nThis uses customer affinities to further personalize results.\n\nMixed Strategy\nCombine multiple recommendation algorithms in a single request to get diverse results.\n\nGET /mixed?partnerName=X&locale=en_US&userId=user1¤cy=USD&strategy=[...]\n\nStrategy array format:\n[\n  {\"recommendationType\": \"ub\", \"size\": 4},\n  {\"recommendationType\": \"vtv\", \"size\": 3, \"productId\": \"prod1\"},\n  {\"recommendationType\": \"mvop\", \"size\": 3, \"filters\": [\"\\[category\\]\\[=\\]\\[shoes\\]\"]}\n]\n\nAvailable types: ub, ue, vtv, btb, cp, sp, mvoc, mvop, mpoc, mpop, mpol, naoc, naop, tpoc, tpop, mvpoc, mvpop, mm, hdop, hdoc, rvp, lpt\n\nEach strategy specifies its algorithm type, the number of products to return, and, optionally, its own filters.\n\nManual Merchandising in Mixed\nUse mm to include specific products you want to promote. The productId field is required.\n\n{\"recommendationType\": \"mm\", \"size\": 3, \"productId\": \"featured1,featured2,featured3\"}\n\nFull example:\n\nGET /mixed?partnerName=X&locale=en_US¤cy=TRY&strategy=[{\"recommendationType\":\"ub\",\"size\":5},{\"recommendationType\":\"mm\",\"size\":3,\"productId\":\"promo1,promo2,promo3\"},{\"recommendationType\":\"mvop\",\"size\":2}]\n\nPass product IDs as comma-separated values.\n\nProducts are returned in the order you specify.\n\nOnly in-stock products are returned.\n\nMultiple Item IDs in Item-Based Algorithms\nGet recommendations based on multiple products at once by passing comma-separated IDs:\n\nGET /vtv?partnerName=X&locale=en_US&productId=item1,item2,item3&size=10¤cy=USD\n\nSupported endpoints are /vtv, /btb, /cp, /sp. It is useful when you want recommendations based on multiple items in a cart or wishlist.\n\nGroup Products\nInclude product variants (e.g., different sizes/colors) in the response using getGroupProducts.\n\nGET /ub?partnerName=X&locale=en_US&userId=user1&getGroupProducts=true&groupProductsFields=price,in_stock,product_attributes.color\n\nParameters\n\ngetGroupProducts=true — Enable variant products in response\n\ngroupProductsFields — Additional fields to include (comma-separated)\n\nResponse structure\n{\n  \"item_id\": \"shoe-blue-m\",\n  \"group_products\": [\n    {\"item_id\": \"shoe-blue-s\", \"price\": {\"USD\": 99}, \"in_stock\": 1},\n    {\"item_id\": \"shoe-blue-l\", \"price\": {\"USD\": 99}, \"in_stock\": 1}\n  ]\n}\n\nVariants are grouped by groupcode. You can request nested fields, such as product_attributes.color.\n\nFilter Chaining with asteriks (*)\nTo combine multiple filters with AND logic, use *.  Here is an example of applying multiple filters:\n\nGET \n...&filter=[category][=][shoes]*[brand][=][nike]*[price][<][100]"
      parameters:
      - name: algorithm-name
        in: path
        required: true
        schema:
          type: string
      security:
      - RequestToken: []
      responses:
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    TooManyRequests:
      description: Too Many Requests. The published per-endpoint rate limit was exceeded; back off and retry, honouring Retry-After when present.
      content:
        application/json:
          example:
            message: Too Many Requests
            status: 429
  securitySchemes:
    RequestToken:
      type: apiKey
      in: header
      name: X-REQUEST-TOKEN
      description: Insider One API key (request token) generated in the InOne panel.
externalDocs:
  description: Insider One API reference
  url: https://academy.insiderone.com/docs/api-reference-welcome
x-provenance:
  generated: '2026-08-13'
  method: derived
  source: postman/insider-one-apis.postman_collection.json
  source_url: https://documenter.gw.postman.com/api/collections/24851117/2sB3dSR9bM
  publisher_page: https://developers.insiderone.com/
  note: Insider One publishes a single public Postman collection covering every REST API. This document is the subset of that collection served from recommendation.api.useinsider.com.