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, SKUs, and searchable custom fields
Attribute-based filtering (price range, availability, stock status)
Category and taxon filtering
Faceted search with filter counts
Flexible sorting options (including sortable product custom fields via sort=cf_{namespace}_{key})

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
// Plus any product custom field marked sortable, e.g. cf_custom_label / -cf_custom_label

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: 'opt_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.

Making a field filterable

A resource’s filters come from its model’s allowlists, and nowhere else. Spree generates its API reference and SDK types from them, so the Querying reference lists what core declares. Filters your app adds take effect in the API immediately; to use them from TypeScript, declare them as shown below, since the published SDK types are generated from core alone.

server/config/initializers/spree.rb

Spree.ransack.add_attribute(Spree::Product, :erp_id)
Spree.ransack.add_association(Spree::Product, :brand)
Spree.ransack.add_scope(Spree::Product, :featured, type: 'boolean')
Spree.ransack.add_scope(Spree::Product, :by_brand, type: 'id')

Give a model a search filter (q[search]=term) by naming the attributes it matches, partially and case-insensitively. Attributes of associated records are named with the association as a prefix:

server/app/models/spree/brand_decorator.rb

base.search_by :name, :code

search is offered to the Store and Seller APIs only when each attribute it matches is one that API may filter on. The API reference describes it from the attributes. Declare the type of a scope’s argument: 'boolean' for a scope taking none (q[featured]=true), or 'text', 'id', 'decimal', 'integer', 'date' or 'datetime' for one value. A list of kinds (%w[decimal decimal]) means several arguments in order, and { list: 'id' } means any number of them. A scope declared without a type is published as taking one text value. Every entry is a filter any caller of that API can run. Keep back-office fields out of the Store API with private_ransackable_attributes, and add associations the storefront may filter through to storefront_ransackable_associations.

Using your own filters from TypeScript

The SDKs type each list() call with the filters Spree itself declares. A filter your app adds works in the API at once, but TypeScript rejects it until it is declared, because the published types cannot know about it. There are three ways to use it. Generate the declarations (recommended). This reads your app’s filters, the ones Spree declares and the ones you added, and writes a declaration file into each app in your project, for the SDK that app uses. Run it from the project root:

Spree CLI
Without CLI

spree filters types

(cd server && bin/rails spree:api:filter_tables > ../filter-tables.json)
npx @spree/cli filters types --from filter-tables.json

It writes src/types/spree-filters.d.ts into each app that exists:

App	SDK
`apps/storefront`	`@spree/sdk`
`apps/dashboard`	`@spree/admin-sdk`
`apps/seller-dashboard` (marketplaces)	`@spree/seller-sdk`

Run it again after you add or change a filter, and commit the generated files with the app code that uses them. For an app outside this layout, write one file for the SDK it uses: spree filters types --api store --out path/to/spree-filters.d.ts. After that, every list() call accepts and autocompletes your filters and sort fields, and a misspelled one is still a compile error. Send it unchecked. Filters inside q are sent as given, without type checking or autocomplete:

await client.products.list({
  name_cont: 'shirt',
  q: { erp_id_eq: 'ERP-1' },
})

Declare it by hand. Each resource has an empty interface in the SDK (ProductFilterExtensions, OrderFilterExtensions, …) that is part of its filter type, and TypeScript merges your declaration into it. The file must contain an import or export; without one, it replaces the SDK’s types instead of adding to them:

src/types/spree.d.ts

export {}

declare module '@spree/sdk' {
  interface ProductFilterExtensions {
    erp_id_eq?: string
    featured?: boolean
  }
  // Sort fields, as keys
  interface ProductSortExtensions {
    erp_id: true
  }
}

Name each filter the way the API receives it, with its predicate (erp_id_eq, erp_id_in for a list) or a scope by its name. Type amounts as decimal strings, counts as numbers and flags as booleans.

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 installing the spree_meilisearch gem and switching to Meilisearch for typo tolerance, relevance ranking, and faster faceted search.

server/config/initializers/spree.rb

Spree.search_provider = 'SpreeMeilisearch::SearchProvider'

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

Develop

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

Making a field filterable

Using your own filters from TypeScript

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

​Making a field filterable

​Using your own filters from TypeScript

​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

Making a field filterable

Using your own filters from TypeScript

Pagination

Search Providers

Related Documentation