Overview

Filters are important features of e-commerce websites and mobile apps. They let consumers search for products efficiently based on characteristics such as brand, price, color, or size. When you integrate filters into your setup, your ads align with the filters that shoppers select. This integration improves ad relevance and performance.

Add product filter elements to catalog feed

To integrate filters, you must include filter information in the custom_labels attribute of your catalog feeds. This information lets the Kamino platform consider these filters when selecting ads.

Express the values as a comma-separated array of key=value pairs.

Example:

[color=red,size=XL,material=leather,price_range=50-100]

For full product feed integration details, see Product catalog attributes.

Additional elements to include in the fill-grid request

To improve the accuracy and relevance of ads that the Kamino Delivery Engine returns, you can add filter parameters to your fill-grid request. These filters help ensure that the engine returns only ads that contain eligible products to shoppers.

Filter parameters

Filter parameters let you define product selection criteria. When you pass several filter parameters in a request, the engine interprets them using a logical AND. This means the product or ad must satisfy all filters to be eligible.

Filter syntax

Use the following syntax to filter:

Syntax to apply a single operator to a property

filter[property]=operator__value

Syntax to apply multiple operators to the same property

filter[property][X]=operator1__value1&filter[property][X]=operator2__value2 

Replace X with a zero-based index (0, 1, 2, etc.). Don't remove the square brackets.

Accepted operators

The system accepts the following operators:

Examples

1. Price range filter

https://api.kamino-retail.com/creatives/fill-grid?retailer=retailer123&page_type=Search&keywords=headphones&filter[price][0]=gte__10&filter[price][1]=lt__50

This request only returns ads where the product price is from 10 through 49.99.

2. Multiple attribute filter

https://api.kamino-retail.com/creatives/fill-grid?retailer=retailer123&page_type=Category&page_id=1234&filter[color]=eq__red&filter[size]=in__M__L__XL

This request returns ads for products that are red and have a size of M, L, or XL.

3. Combined numeric and categorical filters

https://api.kamino-retail.com/creatives/fill-grid?retailer=retailer123&page_type=Search&keywords=jacket&filter[material]=eq__leather&filter[price][0]=gte__100&filter[price][1]=lte__300

This request only returns ads for leather products priced from 100 through 300.

Elements returned in the API response

When you send a fill-grid request with filters, the Kamino Delivery Engine returns a standard JSON response.

Best practices

Roll out filter integration progressively. We recommend that you start with the filters that drive the most traffic and conversions on your website, such as price range, size, or color. You can then gradually expand coverage to additional attributes. This approach ensures a smoother rollout, easier validation, and faster business impact.