Filter, sort, paginate, and expand Admin API responses - Spree

The Admin API uses Ransack for filtering and sorting on collection endpoints. All filter conditions go through the q parameter; sorting and pagination are top-level params.

Filtering

Pass filter conditions via q:

typescript

const orders = await client.orders.list({
  status_eq: 'complete',
  total_gteq: 100,
  email_cont: '@example.com',
})

bash

curl -G 'https://store.example.com/api/v3/admin/orders' \
  -H 'X-Spree-Api-Key: sk_xxx' \
  --data-urlencode 'q[status_eq]=complete' \
  --data-urlencode 'q[total_gteq]=100' \
  --data-urlencode 'q[email_cont][email protected]'

</CodeGroup> <Note> The SDK automatically wraps filter keys in `q[...]` and appends `[]` for array values — pass flat params. </Note>

Common predicates

Predicate	Description	SDK	cURL
`eq`	Equals	`status_eq: 'complete'`	`q[status_eq]=complete`
`not_eq`	Not equals	`status_not_eq: 'canceled'`	`q[status_not_eq]=canceled`
`cont`	Contains (case-insensitive)	`email_cont: '@acme'`	`q[email_cont]=@acme`
`start`	Starts with	`number_start: 'R10'`	`q[number_start]=R10`
`end`	Ends with	`slug_end: 'sale'`	`q[slug_end]=sale`
`lt` / `lteq`	Less than / less than or equal	`total_lteq: 50`	`q[total_lteq]=50`
`gt` / `gteq`	Greater than / greater than or equal	`total_gteq: 100`	`q[total_gteq]=100`
`in`	In a list	`status_in: ['complete', 'canceled']`	`q[status_in][]=complete&q[status_in][]=canceled`
`null` / `not_null`	Is null / not null	`completed_at_not_null: true`	`q[completed_at_not_null]=true`
`true` / `false`	Boolean	`accepts_email_marketing_true: 1`	`q[accepts_email_marketing_true]=1`

Prefixed IDs in filters

Resource ID filters accept Stripe-style prefixed IDs directly. The server decodes them before querying:

typescript

// All orders for a specific customer
const orders = await client.orders.list({
  user_id_eq: 'cus_UkLWZg9DAJ',
})

bash

curl -G 'https://store.example.com/api/v3/admin/orders' \
  -H 'X-Spree-Api-Key: sk_xxx' \
  --data-urlencode 'q[user_id_eq]=cus_UkLWZg9DAJ'

</CodeGroup>

The same applies to _id_in, _id_not_eq, and other ID predicates.

Combining filters

Multiple filters combine with AND:

typescript

// Completed orders over $100 from the last 7 days
const orders = await client.orders.list({
  status_eq: 'complete',
  total_gteq: 100,
  completed_at_gteq: new Date(Date.now() - 7 * 86_400_000).toISOString(),
})

bash

curl -G 'https://store.example.com/api/v3/admin/orders' \
  -H 'X-Spree-Api-Key: sk_xxx' \
  --data-urlencode 'q[status_eq]=complete' \
  --data-urlencode 'q[total_gteq]=100' \
  --data-urlencode 'q[completed_at_gteq]=2026-04-22T00:00:00Z'

</CodeGroup>

Filtering by association

Use underscore notation to filter on associated model attributes:

typescript

// Customers tagged as "wholesale"
const customers = await client.customers.list({
  tags_name_eq: 'wholesale',
})

// Products in a specific category
const products = await client.products.list({
  taxons_id_eq: 'ctg_xxx',
})

bash

curl -G 'https://store.example.com/api/v3/admin/customers' \
  -H 'X-Spree-Api-Key: sk_xxx' \
  --data-urlencode 'q[tags_name_eq]=wholesale'

</CodeGroup>

Custom search scopes

Some resources expose convenience search scopes:

Resource	Scope	Example
Customers	`search`	Full-text over email + first/last name
Customers	`with_min_total_spent`	Filter by lifetime spend
Orders	`multi_search`	Number + email full-text

typescript

const customers = await client.customers.list({
  search: 'jane',
})

const vipCustomers = await client.customers.list({
  with_min_total_spent: 1000,
})

bash

curl -G 'https://store.example.com/api/v3/admin/customers' \
  -H 'X-Spree-Api-Key: sk_xxx' \
  --data-urlencode 'q[search]=jane'

</CodeGroup>

Sorting

Use the top-level sort parameter on any list endpoint. Prefix with - for descending. Follows the JSON:API sorting convention.

typescript

// Most recent orders first
const orders = await client.orders.list({
  sort: '-completed_at',
})

// Multiple sort keys (priority left to right)
const customers = await client.customers.list({
  sort: '-total_spent,email',
})

bash

curl -G 'https://store.example.com/api/v3/admin/orders' \
  -H 'X-Spree-Api-Key: sk_xxx' \
  -d 'sort=-completed_at'

</CodeGroup>

Sortable columns are limited to those whitelisted on the model (Ransack's whitelisted_ransackable_attributes). Sorting on a virtual column (e.g., a serializer-computed field like display_total_spent) is not supported.

Pagination

All collection endpoints return paginated results. Control with page and limit:

typescript

const { data: orders, meta } = await client.orders.list({
  page: 2,
  limit: 50,
})

// meta.count, meta.pages, meta.previous, meta.next ...

bash

curl -G 'https://store.example.com/api/v3/admin/orders' \
  -H 'X-Spree-Api-Key: sk_xxx' \
  -d 'page=2' \
  -d 'limit=50'

</CodeGroup>

Parameter	Default	Max	Description
`page`	`1`	—	Page number (1-indexed)
`limit`	`25`	`100`	Records per page

Pagination metadata

Responses include a meta object:

json

{
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 50,
    "count": 327,
    "pages": 7,
    "from": 51,
    "to": 100,
    "in": 50,
    "previous": 1,
    "next": 3
  }
}

Field	Description
`page`	Current page number
`limit`	Records per page
`count`	Total number of matching records
`pages`	Total number of pages
`from` / `to` / `in`	Position range / count of this page
`previous` / `next`	Previous/next page number, or `null`

Expanding associations

Most admin endpoints return slim payloads by default — associations are returned as IDs. Use the expand parameter to include related resources inline:

typescript

const order = await client.orders.get('or_xxx', {
  expand: ['items', 'fulfillments', 'payments', 'customer'],
})

// Nested expand
const customer = await client.customers.get('cus_xxx', {
  expand: ['addresses', 'store_credits'],
})

bash

curl -G 'https://store.example.com/api/v3/admin/orders/or_xxx' \
  -H 'X-Spree-Api-Key: sk_xxx' \
  -d 'expand=items,fulfillments,payments,customer'

</CodeGroup>

Nested expand

Use dot notation up to 4 levels deep:

typescript

const order = await client.orders.get('or_xxx', {
  expand: ['items.variant.product', 'fulfillments.tracking'],
})

A nested expand implicitly includes its parent — expand: ['items.variant'] returns both items and their variant data.

What can I expand?

Each endpoint documents its supported expand keys in the OpenAPI reference. Common admin expansions:

Resource	Common expands
Orders	`items`, `fulfillments`, `payments`, `customer`, `discounts`, `adjustments`, `billing_address`, `shipping_address`
Customers	`addresses`, `store_credits`, `orders`
Products	`variants`, `media`, `option_types`, `categories`

Field selection

Use the fields parameter to request only specific fields on a resource. Reduces payload size for bandwidth-sensitive integrations:

typescript

const orders = await client.orders.list({
  fields: ['number', 'total', 'status', 'completed_at'],
})

bash

curl -G 'https://store.example.com/api/v3/admin/orders' \
  -H 'X-Spree-Api-Key: sk_xxx' \
  -d 'fields=number,total,status,completed_at'

</CodeGroup>

Rules:

id is always included
Expanded associations return their full payload regardless of fields
Field selection applies to the top-level resource only

<Note> TypeScript types in `@spree/admin-sdk` remain fully typed regardless of `fields`. At runtime, only the requested fields are present — the rest are `undefined`. </Note>