Top Sellers

The Top Sellers algorithm recommends products based on their purchase counts over the last 30 days. It works best on the main page.

Endpoint

GET https://recommendation.api.useinsider.com/v2/top-sellers

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 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 which is assigned by Insider One	String	No
excludeViewDay	30	After how many days viewed products should 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 purchased products should 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 products of the response	Boolean	No
city	Milan	Requested city information	String	No
country	Italy	Requested country information	String	No
productId	ABC123CBA	Current product ID	String	No

Algorithm Customizations

The Top Sellers algorithm also provides users with product recommendations based on categories and locations.

To retrieve category-based best-selling products, the API endpoint should include the categoryList parameter with valid category values from the Product Catalog.
To obtain the best-selling products based on location, country, and city information, the API endpoint should include these parameters.

Please refer to the table below for the conditions and parameters to customize the Top Sellers algorithm.

Variant	Condition	Parameter(s)
Top Sellers	No filters	Default (no country, no categoryList)
Top Sellers of Category	Category filter provided	categoryList=[cat1, cat2, ...]
Top Sellers of Location	Geographic filter provided	country=<country_code>&city=<optional_city>

When categoryList is provided, recommendations are filtered to show only the Top Seller products within the specified categories. Recommendations served in the API response will be abbreviated as mpoc for Top Sellers of Category recommendations.

When Top Sellers of Location recommendations are requested, the API endpoint will present recommendations with the mpol abbreviation.

Sample Request

The sample below displays a request to Top Sellers, an algorithm that recommends products with the highest purchase counts over the last 30 days.

https://recommendation.api.useinsider.com/v2/top-sellers?locale={Locale}&partnerName={PartnerName}

Sample Response

{
        "success": true,
        "total": 1,
        "types": {
        "mpop": 1
        },
        "data": [
        {
        "image_url": "test.image_url.com",
        "name": "Original Air-dried Beef recipe for dogs",
        "item_id": "46177313784082",
        "url": "test.url.com",
        "description": "Having access to lush fields of grass year-round makes New Zealand free-range, grass-fed beef among the best in the world.",
        "in_stock": 1,
        "price": {
        "USD": 29.58
        },
        "groupcode": "8528988209426",
        "locale": "en_US",
        "product_attributes": {
        "activation_date": "2023-08-11",
        "shopify_tag": [
        "air-dried",
        "beef",
        "dog"
        ]
        },
        "stock_count": 99,
        "category": [
        "Dog Food",
        "Pets Collection"
        ],
        "discount": {
        "USD": 0.0
        },
        "original_price": {
        "USD": 29.58
        }
        }
        ]
        }

Sample Request for Top Sellers of Category

https://recommendation.api.useinsider.com/v2/most-popular?locale={Locale}&partnerName={PartnerName}&currency={Currency}&categoryList=[“Dog Food”]

Sample Response

{
        "success": true,
        "total": 1,
        "types": {
        "mpoc": 1
        },
        "data": [
        {
        "image_url": "test.image_url.com",
        "name": "Original Air-dried Beef recipe for dogs",
        "item_id": "46177313784082",
        "url": "test.url.com",
        "description": "Having access to lush fields of grass year-round makes New Zealand free-range, grass-fed beef among the best in the world.",
        "in_stock": 1,
        "price": {
        "USD": 29.58
        },
        "groupcode": "8528988209426",
        "locale": "en_US",
        "product_attributes": {
        "activation_date": "2023-08-11",
        "shopify_tag": [
        "air-dried",
        "beef",
        "dog"
        ]
        },
        "stock_count": 99,
        "category": [
        "Dog Food",
        "Pets Collection"
        ],
        "discount": {
        "USD": 0.0
        },
        "original_price": {
        "USD": 29.58
        }
        }
        ]
        }

Sample Request for Top Sellers of Location

https://recommendation.api.useinsider.com/v2/most-popular?locale={Locale}&partnerName={PartnerName}&currency={Currency}&country={country}&city={city}

Sample Response

{
        "success": true,
        "total": 1,
        "types": {
        "mpol": 1
        },
        "data": [
        {
        "image_url": "test.image_url.com",
        "name": "Original Air-dried Beef recipe for dogs",
        "item_id": "46177313784082",
        "url": "test.url.com",
        "description": "Having access to lush fields of grass year-round makes New Zealand free-range, grass-fed beef among the best in the world.",
        "in_stock": 1,
        "price": {
        "USD": 29.58
        },
        "groupcode": "8528988209426",
        "locale": "en_US",
        "product_attributes": {
        "activation_date": "2023-08-11",
        "shopify_tag": [
        "air-dried",
        "beef",
        "dog"
        ]
        },
        "stock_count": 99,
        "category": [
        "Dog Food",
        "Pets Collection"
        ],
        "discount": {
        "USD": 0.0
        },
        "original_price": {
        "USD": 29.58
        }
        }
        ]
        }

Fallback Algorithms

If the products from Top Sellers are not enough to fill the response data, some fallback algorithms below fill it:

Most purchased of the category without excluding the rightmost item in the categoryList

If the city or country is given in as a query parameter, the fallback algorithms that fill it are:

Most purchased of the category
Most purchased of the category, without excluding the right-most item in the categoryList
Most purchased of the Partner