Filtering Recommendation Responses

Filtering allows you to refine recommendation results to match your users' needs and preferences. Common use cases include:

• Exclude already-viewed products - Don't recommend products the user has seen

• Price range filtering - Show only products within budget

• Category/brand filtering - Focus on specific product types

• Stock filtering - Only recommend in-stock items

• Attribute filtering - Filter by custom product attributes (color, size, rating, etc.)

This increases relevance, improves user experience, and boosts conversion rates.

Basic Syntax

https://recommendation.api.useinsider.com/v2/{algorithm}?...\&filter=[{field}][{operator}][{value}]

Here is an example with a single filter that returns  products with prices greater than 100 USD:

?filter=[price.USD][>][100]

Multiple Filters

You can pass multiple filter parameters to combine conditions. Each condition is chained together via an asterisk (*).

Syntax

?filter=[field1][operator1][value1]*[field2][operator2][value2]

How Multiple Filters work

Multiple filters are combined with AND logic - products must match ALL conditions to be included.

Example 1: Exclude current product + filter by category

?filter=[item_id][!=][PRODUCT_ID]*[category][~][Shoes]

This filter returns products that are NOT PRODUCT_ID AND contain "Shoes" in the category.

Example 2: Price range + in stock

?filter=[price.USD][>][50]*[price.USD][<][200]*[in_stock][=][1]

This filter returns products between $50-$200 AND in stock.

Operator Reference

Date Field Values

Insider 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.

The date fields available for filtering are: created_at and modified_at.

Operator Compatibility

Date 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).

The most appropriate operators for date fields are:

• After (>)

• Before (<)

• Is (=)

• Is Not (!=)

Relative Date Filtering

Date filters also support relative unit values, allowing you to easily filter based on time relative to the current moment (now).

• Anchor: now

• Units: w (week), d (day), h (hour)

• Modifiers: Use + to add units or - to subtract units.

You can see the examples below:

Multiple Value Filtering (In / Not-In Filter Behavior)

Match fields against multiple values by separating them with:

||

Supported by all operators except between and not between.

Examples:

• Get products from multiple brands:

?filter=[brand][=][Niki||Abiba||Pamu]

• Exclude multiple colors:

?filter=[color][!=][Red||Green||Blue]

Get products with categories containing any of these terms:

?filter=[category][~][Shoes||Boots||Sneakers]

Advanced Filtering with AND/OR

Combine multiple filters using logical operators within a single filter parameter.

• And (*) = both conditions must be true

• Or (|) = either condition can be true

Examples

• AND Example: Price range AND brand

?filter=([price.USD][>][100]*[brand][=][Niki]) 

• OR Example: Multiple categories

?filter=([category][~][Shoes]|[category][~][Boots])

• Complex: (A AND B) OR C

Get products that are either (cheap AND in stock) OR highly rated:

?filter=((price.USD][<][50]*[in_stock][=][1])|[rating][>=][5])

You can also use multiple parameters to achieve AND logic more simply:

?filter=[price.USD][<][50]&filter=[in_stock][=][1]&filter=[rating][>=][5]

This is often clearer than using complex parentheses.

Dynamic Filters

Use ${value} to reference the source product's field value in your filter. The expression is computed at request time using the actual product data.

Supported Expressions

• ${value} - Use the product's field value as-is

• ${value*1.2} - Multiply by 1.2 (20% increase)

• ${value*0.8} - Multiply by 0.8 (20% decrease)

• ${value*0.8}:${value*1.3} - Range with dynamic bounds

Examples

• Match the product's category dynamically:

?categoryList=${value}&productId=PRODUCT_ID

If the product has a category "Shoes", recommendations are filtered to "Shoes" only.

• Show products in a similar price range (±30%):

?productId=PRODUCT_ID&filter=[price.EUR][><][${value}:${value*1.3}]

If the product costs €100, it shows products priced €100-€130.

Filter Validation Errors

When filters are invalid, the API returns specific error messages with HTTP status codes:

Format & Syntax Errors (400)

Field Errors (400 or 422)

Operator Errors (400)

Value Errors (400 or 422)

Field-Specific Validations (400)

Dynamic Filter Errors (400)

Limitations