Quickstart - Liquid Rewards API

This guide walks through making your first product search, fetching full product details, and paginating results.

Prerequisites

An API key. See Authentication.
A tool to make HTTP requests (curl, Postman, or your language of choice).

Search for products

Send a POST request to /v1/discovery/products/search with a free-text query and optional structured filters.

curl https://rewardsbot-prod.liquidrewardsapi.com/v1/discovery/products/search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "running shoes",
    "criteria": [
      { "field": "on_sale",  "operator": "=", "value": true },
      { "field": "in_stock", "operator": "=", "value": true }
    ],
    "per_page": 25
  }'

The response includes items, page_index, page_size, and a next_cursor for the next page.

Paginate to the next page

Pass the next_cursor from the previous response back as cursor to fetch the next page. No other fields are required when paginating.

curl https://rewardsbot-prod.liquidrewardsapi.com/v1/discovery/products/search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cursor": "opaque-next-page-cursor" }'

Cursors and their backing search sessions expire. A 410 response means you need to start a new search.

Get full product details

Each search result includes a slug. Use it to fetch full product details, including pricing, brand, merchant, and availability.

curl https://rewardsbot-prod.liquidrewardsapi.com/v1/discovery/products/PRODUCT_SLUG \
  -H "x-api-key: YOUR_API_KEY"

Reuse filters with criteria sets

Save commonly-used filter bundles as criteria sets and apply them by ID on future searches.

curl 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",
    "criteria": [
      { "field": "on_sale",       "operator": "=",  "value": true },
      { "field": "sale_discount", "operator": ">=", "value": 0.2 }
    ]
  }'

Then reference it from a search:

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

Next steps

Browse the full API Reference for every endpoint, parameter, and schema.
Explore the catalog of available filter fields and operators in the search request schema.

​Prerequisites

​Next steps

Prerequisites

Next steps