Criteria Filters: Structured Product Filtering

Criteria filters let you build precise, structured product searches that go far beyond free-text queries. While the query field in a product search uses natural language, criteria work as explicit filter predicates applied directly to product data fields — giving you deterministic, repeatable control over exactly which products appear in results.

How Criteria Work

Each criterion is a simple three-field object:

field

string

required

The product attribute to filter on (e.g., "brand", "final_price", "in_stock").

operator

string

required

The comparison operation to apply. Available operators depend on the field type: =, !=, >=, <=, like, not_like.

value

string | number | boolean

required

The value to compare the field against. The type must match the field type (text fields take strings, numeric fields take numbers, boolean fields take true/false).

Example — filter to Nike products:

{ "field": "brand", "operator": "=", "value": "Nike" }

Multiple criteria in an array are applied as AND conditions — all criteria must be satisfied for a product to appear in results.

Available Fields

Text Fields

Text fields support the operators: =, !=, like, not_like. Use like and not_like for partial matching (similar to a SQL LIKE with implicit wildcards).

Field	Description
`any`	Matches against any text field on the product
`name\|\|description\|\|brand`	Matches the product name, description, or brand
`brand`	Product brand name
`category`	Product category
`color`	Product color
`condition`	Product condition (e.g., `"new"`, `"refurbished"`)
`country`	Country of origin or availability
`currency`	Currency code for pricing (e.g., `"USD"`)
`gender`	Target gender (e.g., `"women"`, `"men"`, `"unisex"`)
`genre`	Product genre (used in media and entertainment)
`manufacturer`	Manufacturer name
`material`	Primary material (e.g., `"leather"`, `"mesh"`)
`model`	Model name or number
`publisher`	Publisher name (used for books, games, media)
`size`	Product size
`subtitle`	Product subtitle
`tags`	Product tags
`availability`	Availability status string
`id`	Product identifier
`barcode`	Product barcode (UPC/EAN)
`sku`	Stock keeping unit
`mpn`	Manufacturer part number
`asin`	Amazon Standard Identification Number
`merchant.id`	Merchant identifier
`merchant.name`	Merchant name
`merchant_category_ids`	Merchant-assigned category IDs
`seller_party`	Selling party identifier

Numeric Fields

Numeric fields support the operators: =, !=, >=, <=.

Field	Description
`regular_price`	Original retail price before any discounts
`final_price`	Final price after all discounts applied
`sale_price`	Sale price (when product is on sale)
`ship_price`	Shipping cost
`sale_discount`	Discount amount or percentage
`stock_quantity`	Number of units in stock

Boolean Fields

Boolean fields support the operators: =, !=. Values must be true or false.

Field	Description
`on_sale`	Whether the product is currently on sale
`in_stock`	Whether the product is currently in stock

Criteria Examples

Here are common filter patterns you can adapt for your use case:

[
  { "field": "on_sale",     "operator": "=",  "value": true },
  { "field": "in_stock",    "operator": "=",  "value": true },
  { "field": "brand",       "operator": "=",  "value": "Nike" },
  { "field": "final_price", "operator": "<=", "value": 100 },
  { "field": "category",    "operator": "like","value": "running shoe" },
  { "field": "gender",      "operator": "=",  "value": "women" }
]

Other useful patterns:

// Exclude a specific brand
{ "field": "brand", "operator": "!=", "value": "Generic" }

// Filter to new condition only
{ "field": "condition", "operator": "=", "value": "new" }

// Price range (combine two criteria)
{ "field": "final_price", "operator": ">=", "value": 50 }
{ "field": "final_price", "operator": "<=", "value": 150 }

// Find products by partial category name
{ "field": "category", "operator": "like", "value": "sneaker" }

// Filter by specific merchant
{ "field": "merchant.name", "operator": "=", "value": "Nike" }

When combining query (free-text) with criteria (structured filters), both are applied together. Products must satisfy the full-text relevance of the query and all criteria predicates.

Criteria Sets

Criteria sets let you save a group of frequently used criteria under a named ID. Instead of repeating the same filter array in every request, you define it once and reference it by ID. Criteria sets support the full filter definition including an optional query and exclude_query.

Criteria sets are great for encoding business rules — like always filtering to in-stock, on-sale items — without repeating them in every request.

Criteria Set Schema

string

required

An alphanumeric identifier for the criteria set (e.g., "summer-sale"). Must be unique within your account. Hyphens and underscores are allowed.

name

string

required

A human-readable label for the criteria set (e.g., "Summer Sale Items").

query

string

An optional free-text filter applied when this criteria set is used. Functions the same as the query field in a product search.

exclude_query

string

An optional negative text filter. Products matching this string are excluded when the criteria set is applied.

criteria

array

required

The array of criterion objects that make up this set.

Creating a Criteria Set

curl -X POST https://rewardsbot-prod.liquidrewardsapi.com/v1/discovery/products/criteria-sets \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "summer-sale",
    "name": "Summer Sale Items",
    "query": "summer",
    "criteria": [
      { "field": "on_sale", "operator": "=", "value": true },
      { "field": "in_stock", "operator": "=", "value": true }
    ]
  }'

Applying Criteria Sets in a Search

Pass saved criteria set IDs in the criteria_set_ids array of a product search request:

{
  "query": "swimwear",
  "criteria_set_ids": ["summer-sale"]
}

You can combine criteria_set_ids with inline criteria in the same request. Both are applied as AND conditions — all criteria from every source must be satisfied.

{
  "query": "swimwear",
  "criteria_set_ids": ["summer-sale"],
  "criteria": [
    { "field": "gender", "operator": "=", "value": "women" }
  ]
}

Managing Criteria Sets

Create a criteria set

POST /v1/discovery/products/criteria-sets with your set definition. The id you provide becomes the permanent reference key.

List all criteria sets

GET /v1/discovery/products/criteria-sets returns all saved criteria sets for your account.

Retrieve a specific criteria set

GET /v1/discovery/products/criteria-sets/{id} returns the full definition of a single criteria set.

Update a criteria set

PUT /v1/discovery/products/criteria-sets/{id} replaces the criteria set with a new definition.

Delete a criteria set

DELETE /v1/discovery/products/criteria-sets/{id} removes the criteria set. Searches referencing the deleted ID will return an error.

Deleting a criteria set that is actively referenced in your search requests will cause those requests to fail. Update or remove criteria_set_ids references before deleting a set.

​How Criteria Work

​Available Fields

​Text Fields

​Numeric Fields

​Boolean Fields

​Criteria Examples

​Criteria Sets

​Criteria Set Schema

​Creating a Criteria Set

​Applying Criteria Sets in a Search

​Managing Criteria Sets

How Criteria Work

Available Fields

Text Fields

Numeric Fields

Boolean Fields

Criteria Examples

Criteria Sets

Criteria Set Schema

Creating a Criteria Set

Applying Criteria Sets in a Search

Managing Criteria Sets