Skip to main content
The affiliate discovery search API lets you query a catalog of affiliate products with natural language and structured filters. This guide shows how to build effective searches, apply filters, and paginate through results.
Results include expires_at — cursors and product slugs expire after this timestamp. Build your UI to handle graceful expiry.

​
Basic Text Search

Send a POST request to /v1/discovery/products/search with your query string. The x-api-key header is required for all /v1/discovery/* endpoints. 
curl -X POST https://rewardsbot-prod.liquidrewardsapi.com/v1/discovery/products/search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "wireless headphones", "per_page": 25}'

​
Filtering with Criteria

Combine a free-text query with a criteria array to apply structured filters. Each criterion specifies a field, an operator, and a value: 
{
  "query": "running shoes",
  "criteria": [
    { "field": "on_sale",     "operator": "=",  "value": true    },
    { "field": "in_stock",    "operator": "=",  "value": true    },
    { "field": "final_price", "operator": "<=", "value": 100.00  },
    { "field": "gender",      "operator": "=",  "value": "women" }
  ]
}

​
Excluding Results

Use exclude_query to filter out unwanted results by keyword. This is useful for narrowing a broad category query: 
{
  "query": "shoes",
  "exclude_query": "trail hiking"
}

​
Using Saved Criteria Sets

If you have pre-configured criteria sets saved in your account, reference them by ID to apply them without re-specifying each filter: 
{
  "query": "running shoes",
  "criteria_set_ids": ["summer-sale", "womens-athletic"]
}

​
Pagination

All searches return a next_cursor when more results exist. Pass it as the cursor field in your next request to retrieve the following page: 
{ "cursor": "opaque-cursor-value-from-previous-response" }
Do not combine cursor with other search parameters — the cursor already encodes all query context from the original request. Results expire after the expires_at timestamp returned in the response.

​
Fetching Product Details

Once you have a product slug from search results, retrieve its full details with a GET request: 
curl https://rewardsbot-prod.liquidrewardsapi.com/v1/discovery/products/PRODUCT_SLUG \
  -H "x-api-key: YOUR_API_KEY"

​
Understanding Product Data

Each product result contains the following key fields:
​
id
string
Unique numeric identifier for the product.
​
slug
string
URL-friendly identifier used to fetch full product details.
​
name
string
Display name of the product.
​
description
string
Full product description.
​
brand
string
Brand name of the product.
​
category
string
Product category classification.
​
image_url
string
URL of the product image.
​
product_url
string
Direct URL to the product page.
​
merchant_url
string
URL of the merchant’s storefront.
​
price.display
string
Human-readable formatted price string (e.g., "$89.99").
​
price.value
number
Numeric price value for calculations and filtering.
​
price.on_sale
boolean
Whether the product is currently on sale.
​
price.sale_discount
number
Discount percentage applied when the product is on sale.
​
merchant.name
string
Display name of the merchant.
​
merchant.logo_url
string
URL of the merchant’s logo image.
​
availability
string
Current stock status of the product (e.g., "in_stock", "out_of_stock").