Search & Filtering

Overview

Spree provides powerful search, filtering, and sorting capabilities for products and other resources. The Store API supports:

Full-text search across product names and SKUs
Attribute-based filtering (price range, availability, stock status)
Category and taxon filtering
Faceted search with filter counts
Flexible sorting options

Product Search

Use the search parameter for full-text search across product fields:

const { data: products } = await client.products.list({
  search: 'tote bag',
  limit: 12,
})

const { data: products } = await adminClient.products.list({
  search: 'tote bag',
  limit: 12,
})

curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag&limit=12' \
  -H 'X-Spree-API-Key: pk_xxx'

Filtering Products

By Price Range

const { data: products } = await client.products.list({
  price_gte: 20,
  price_lte: 100,
})

const { data: products } = await adminClient.products.list({
  price_gte: 20,
  price_lte: 100,
})

curl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=20&q[price_lte]=100' \
  -H 'X-Spree-API-Key: pk_xxx'

By Availability

const { data: products } = await client.products.list({
  in_stock: true,
})

const { data: products } = await adminClient.products.list({
  in_stock: true,
})

curl 'https://api.mystore.com/api/v3/store/products?q[in_stock]=true' \
  -H 'X-Spree-API-Key: pk_xxx'

By Category

// Filter by category ID (includes descendants)
const { data: products } = await client.products.list({
  in_category: 'ctg_xxx',
})

// Multiple categories (OR logic, checkbox filters)
const { data: products } = await client.products.list({
  in_categories: ['ctg_shirts', 'ctg_pants'],
})

// Filter by category ID (includes descendants)
const { data: products } = await adminClient.products.list({
  in_category: 'ctg_xxx',
})

// Multiple categories (OR logic)
const { data: products } = await adminClient.products.list({
  in_categories: ['ctg_shirts', 'ctg_pants'],
})

# Filter by category ID (includes descendants)
curl 'https://api.mystore.com/api/v3/store/products?q[in_category]=ctg_xxx' \
  -H 'X-Spree-API-Key: pk_xxx'

# Multiple categories (OR logic)
curl 'https://api.mystore.com/api/v3/store/products?q[in_categories][]=ctg_shirts&q[in_categories][]=ctg_pants' \
  -H 'X-Spree-API-Key: pk_xxx'

By Tags

const { data: products } = await client.products.list({
  tags_name_cont: 'sale',
})

const { data: products } = await adminClient.products.list({
  tags_name_cont: 'sale',
})

curl 'https://api.mystore.com/api/v3/store/products?q[tags_name_cont]=sale' \
  -H 'X-Spree-API-Key: pk_xxx'

Sorting

// Sort by price (low to high)
const sorted = await client.products.list({
  sort: 'price',
})

// Available sort options (prefix '-' for descending; use '-available_on' for newest):
// price, -price, name, -name, available_on, -available_on, best_selling

const { data: products } = await adminClient.products.list({
  sort: 'price',
})

curl 'https://api.mystore.com/api/v3/store/products?sort=price' \
  -H 'X-Spree-API-Key: pk_xxx'

Get available filter options for building a faceted search UI. Returns an array of typed filter objects (price range, availability, option types, categories) with counts, plus sort and pagination metadata:

const filters = await client.products.filters()
// {
//   filters: [
//     { id: 'price', type: 'price_range', min: 9.99, max: 199.99, currency: 'USD' },
//     { id: 'availability', type: 'availability', options: [{ id: 'in_stock', count: 42 }, { id: 'out_of_stock', count: 3 }] },
//     { id: 'optt_xxx', type: 'option', name: 'size', label: 'Size', kind: 'dropdown', options: [{ id: 'optval_xxx', name: 'Small', label: 'Small', position: 1, color_code: null, image_url: null, count: 12 }] },
//     { id: 'categories', type: 'category', options: [{ id: 'ctg_xxx', name: 'Clothing', permalink: 'clothing', count: 45 }] },
//   ],
//   sort_options: [{ id: 'manual' }, { id: 'price' }, { id: '-price' }],
//   default_sort: 'manual',
//   total_count: 120,
// }

// Scoped to a specific category
const categoryFilters = await client.products.filters({
  category_id: 'ctg_xxx',
})

# All filters
curl 'https://api.mystore.com/api/v3/store/products/filters' \
  -H 'X-Spree-API-Key: pk_xxx'

# Scoped to a category
curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \
  -H 'X-Spree-API-Key: pk_xxx'

Filtering Other Resources

The Store API uses query parameters prefixed with q[] for filtering any resource collection. Common filter predicates:

Equality Predicates

Predicate	Description	Example
`eq`	Equals	`q[status_eq]=active`
`not_eq`	Not equals	`q[status_not_eq]=archived`
`in`	In array	`q[id_in][]=1&q[id_in][]=2`

String Predicates

Predicate	Description	Example
`cont`	Contains	`q[name_cont]=shirt`
`start`	Starts with	`q[name_start]=spree`
`end`	Ends with	`q[email_end]=@example.com`
`i_cont`	Case-insensitive contains	`q[name_i_cont]=SHIRT`

Comparison Predicates

Predicate	Description	Example
`gt`	Greater than	`q[price_gt]=50`
`gteq`	Greater than or equal	`q[quantity_gteq]=10`
`lt`	Less than	`q[price_lt]=100`
`lteq`	Less than or equal	`q[created_at_lteq]=2025-12-31`

NULL Predicates

Predicate	Description	Example
`null`	Is NULL	`q[deleted_at_null]=true`
`not_null`	Is not NULL	`q[published_at_not_null]=true`
`present`	Is not NULL and not empty	`q[image_present]=true`

Only attributes explicitly allowed by each resource can be used for filtering. Attempting to filter on unsupported fields will be silently ignored.

Pagination

All list endpoints support pagination:

const { data: products, meta } = await client.products.list({
  page: 1,
  limit: 24,
})
// meta.count => 150
// meta.pages => 7

const { data: products, meta } = await adminClient.products.list({
  page: 1,
  limit: 24,
})

curl 'https://api.mystore.com/api/v3/store/products?page=1&limit=24' \
  -H 'X-Spree-API-Key: pk_xxx'

See Querying for the full list of filtering, sorting, and pagination options.

Search Providers

Spree uses a pluggable search provider architecture. The default provider uses SQL (ILIKE + Ransack). For production catalogs with 1,000+ products, we recommend switching to Meilisearch for typo tolerance, relevance ranking, and faster faceted search.

# config/initializers/spree.rb
Spree.search_provider = 'Spree::SearchProvider::Meilisearch'

No client-side or API changes are needed — the same q[search], filter params, and sort options work with any provider. See Build a Custom Search Provider for architecture details and how to build custom providers.

Products — Product catalog and listing
Store SDK Products — client.products.list() options and methods
Querying — Store API filtering, sorting, and pagination reference
Admin API querying — Admin API filtering, sorting, and pagination reference
Build a Custom Search Provider — Step-by-step guide
Meilisearch Integration — Setup guide

Getting started

Platform

Catalog

Cart & Checkout

Fulfillment

Extensibility

Overview

Product Search

Filtering Products

By Price Range

By Availability

By Category

By Tags

Sorting

Product Filters (Faceted Search)

Filtering Other Resources

Equality Predicates

String Predicates

Comparison Predicates

NULL Predicates

Search Providers

​Overview

​Product Search

​Filtering Products

​By Price Range

​By Availability

​By Category

​By Tags

​Sorting

​Product Filters (Faceted Search)

​Filtering Other Resources

​Equality Predicates

​String Predicates

​Comparison Predicates

​NULL Predicates

​Pagination

​Search Providers

​Related Documentation

Overview

Product Search

Filtering Products

By Price Range

By Availability

By Category

By Tags

Sorting

Product Filters (Faceted Search)

Filtering Other Resources

Equality Predicates

String Predicates

Comparison Predicates

NULL Predicates

Pagination

Search Providers

Related Documentation