Filtering

Build filters using the type-safe filter DSL:

import { filter, and, or, eq, gte, lte, inValues } from '@commerce-blocks/sdk'

const collection = sdk.collection({ collectionHandle: 'shirts' })
await collection.get({
  filterGroup: filter(and(
    eq('your-attribute', 'your-value'),
    eq('your-second-attribute', 'your-second-value'),
  )),
})

// Numeric range
await collection.get({
  filterGroup: filter(and(
    gte('your-numeric-attribute', 50),
    lte('your-numeric-attribute', 200),
  )),
})

// Multiple values on the same attribute
await collection.get({
  filterGroup: filter(inValues('your-attribute', ['your-value', 'your-second-value'])),
})

Filter operators

Operator	Description
`eq(property, value)`	Equals
`neq(property, value)`	Not equals
`inValues(property, values[])`	In list
`notIn(property, values[])`	Not in list
`gt(property, number)`	Greater than
`gte(property, number)`	Greater than or equal
`lt(property, number)`	Less than
`lte(property, number)`	Less than or equal
`between(property, min, max)`	Within a numeric range
`notBetween(property, min, max)`	Outside a numeric range
`contains(property, string)`	Contains substring
`doesNotContain(property, string)`	Does not contain substring
`beginsWith(property, string)`	Starts with substring
`endsWith(property, string)`	Ends with substring
`isNull(property)`	Property is null
`notNull(property)`	Property is not null

Filter types

The DSL produces FilterGroup and FilterExpression objects. You typically do not construct these manually, but the types are exported if you need to build filters programmatically:

import type { FilterGroup, FilterExpression } from '@commerce-blocks/sdk'

interface FilterExpression {
  property: string
  operator: FilterOperator
  values: (string | number | boolean)[]
}

interface FilterGroup {
  conditional: 'AND' | 'OR'
  expressions: (FilterExpression | FilterGroup)[]
}

The filter() function wraps a single expression in a FilterGroup automatically, so you can pass either an expression or a group:

// Single expression (wrapped in AND group automatically)
filter(eq('your-attribute', 'your-value'))

// Explicit group
filter(and(
  eq('your-attribute', 'your-value'),
  gte('your-numeric-attribute', 50),
))

// Nested groups
filter(and(
  eq('your-attribute', 'your-value'),
  or(
    eq('your-second-attribute', 'your-second-value'),
    eq('your-second-attribute', 'your-third-value'),
  ),
))

In v3, available facets and their counts are fetched at runtime using sdk.facets(). This replaces the facets array that was passed to createClient() in v2.

const facetController = sdk.facets({ collectionHandle: 'shirts' })

facetController.subscribe(({ data, error }) => {
  if (error) {
    console.error('Facet fetch failed:', error.message)
    return
  }
  if (data) {
    console.log(data.facets)
    console.log(data.facetRanges)
  }
})

await facetController.get()

You can also request filtered facet counts by passing the same filterGroup the shopper has selected:

await facetController.get({
  filterGroup: filter(eq('your-attribute', 'your-value')),
})

Filter shorthand

If a single expression is all you need, pass it directly to filter(). It is equivalent to and(...) for one expression.

await collection.get({ filterGroup: filter(eq('your-attribute', 'your-value')) })

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Filter operators

Filter types

Runtime facet discovery

Filter shorthand

Next steps

​Filter operators

​Filter types

​Runtime facet discovery

​Filter shorthand

​Next steps

Filter operators

Filter types

Runtime facet discovery

Filter shorthand

Next steps