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

Last updated: September 29, 2026

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.