How do I filter results on External API list endpoints using the field[operator]=value syntax?

Overview

All Luminous External V1 list endpoints support a consistent filter syntax that lets you narrow results without downloading an entire dataset. Filters are passed as query-string parameters in the form:

?field[operator]=value

You can combine as many filters as you need in a single request by chaining them with &.

Basic syntax

What you want	Example
Exact match	`?status[eq]=open`
Not equal	`?status[neq]=cancelled`
Contains text	`?order_number[contains]=ORD-`
Does not contain	`?name[notcontains]=test`
Greater than or equal	`?total[gte]=500`
Less than	`?total[lt]=10000`
In a list of values	`?id[in]=1,2,3`
Not in a list	`?status[notin]=draft,archived`
Field has a value (not blank)	`?note[set]=true`
Field is blank / unset	`?note[notset]=true`

All supported operators

Operator	Meaning	Works with
`eq`	Equals	All field types
`neq`	Not equals	All field types
`gt`	Greater than	Numbers, Dates
`gte`	Greater than or equal	Numbers, Dates
`lt`	Less than	Numbers, Dates
`lte`	Less than or equal	Numbers, Dates
`contains`	Substring match	Text fields
`notcontains`	Substring exclusion	Text fields
`in`	Matches any value in a comma-separated list	All field types
`notin`	Matches none of the values in the list	All field types
`set`	Field is not null/empty	All field types
`notset`	Field is null/empty	All field types

Stacking filters (AND logic)

To apply multiple conditions, include each filter as a separate query parameter. All conditions are combined with AND:

?created_at[gte]=2025-01-01&created_at[lte]=2025-03-31&status[eq]=shipped

This returns only records created in Q1 2025 that are also in "shipped" status.

Filtering by a list of values

Pass multiple values as a comma-separated list:

?status[in]=open,pending,on_hold

Date and datetime filters

Date-only values (no time component) work as-is:

?created_at[gte]=2025-06-01

If you include a time, append a Z or a numeric UTC offset so the filter matches correctly. Without a timezone indicator, the time is interpreted in your account's configured timezone:

?updated_at[gte]=2025-06-01T00:00:00.000000Z

Boolean filters

Boolean fields accept true, false, 1, or 0:

?sellable[eq]=true
?active[eq]=0

Custom field filters

On endpoints that expose custom fields (such as products and fulfillment orders), prefix the custom field's label with custom_fields_, replacing spaces, dots and dashes with underscores:

?custom_fields_Region[contains]=West ?custom_fields_Product_Type[eq]=Apparel ?custom_fields_Priority[notset]=true

A label of "Product Type" becomes custom_fields_Product_Type.

Multi-field search (OR logic)

Some endpoints expose a single q parameter that searches across several fields at once (for example, name, SKU, and UPC). When available, use it instead of separate per-field filters:

?q[contains]=ACME-001

Check the documentation for the specific endpoint to confirm which fields q covers.

Pagination

Filtering works alongside standard pagination parameters:

?status[eq]=open&page=2&per_page=50

per_page defaults to 10; maximum is 100.
Paginated responses include links and meta objects with page navigation URLs and total counts.

Quick example

Fetch all sales orders created after June 1, 2025 with a total over $500, ordered by recency, 25 per page:

GET /external/v1/sales-orders
  ?created_at[gte]=2025-06-01
  &total[gte]=500
  &per_page=25

Tips

Unknown fields are silently ignored. If you misspell a field name the filter is skipped rather than returning an error, so double-check spelling if results look unfiltered.
Unsupported operators on a field type (for example contains on a numeric field) are also silently ignored.
Not every field on every endpoint is filterable. Refer to the per-endpoint documentation to see which fields are exposed as filters. -Invalid values return an error. An unparseable date (e.g. created_at[gte]=not-a-date) or a nested array value returns 422 instead of being ignored.