Skip to main content

​
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
Use the search parameter for full-text search across product fields: 
const { data: products } = await client.products.list({
  search: 'tote bag',
  limit: 12,
})

​
Filtering Products

​
By Price Range

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

​
By Availability

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

​
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'],
})

​
By Tags

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

​
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
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',
})

​
Filtering Other Resources

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

​
Equality Predicates

PredicateDescriptionExample
eqEqualsq[status_eq]=active
not_eqNot equalsq[status_not_eq]=archived
inIn arrayq[id_in][]=1&q[id_in][]=2

​
String Predicates

PredicateDescriptionExample
contContainsq[name_cont]=shirt
startStarts withq[name_start]=spree
endEnds withq[email_end]=@example.com
i_contCase-insensitive containsq[name_i_cont]=SHIRT

​
Comparison Predicates

PredicateDescriptionExample
gtGreater thanq[price_gt]=50
gteqGreater than or equalq[quantity_gteq]=10
ltLess thanq[price_lt]=100
lteqLess than or equalq[created_at_lteq]=2025-12-31

​
NULL Predicates

PredicateDescriptionExample
nullIs NULLq[deleted_at_null]=true
not_nullIs not NULLq[published_at_not_null]=true
presentIs not NULL and not emptyq[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
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.