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 |
|
Not equal |
|
Contains text |
|
Does not contain |
|
Greater than or equal |
|
Less than |
|
In a list of values |
|
Not in a list |
|
Field has a value (not blank) |
|
Field is blank / unset |
|
All supported operators
Operator | Meaning | Works with |
|---|---|---|
| Equals | All field types |
| Not equals | All field types |
| Greater than | Numbers, Dates |
| Greater than or equal | Numbers, Dates |
| Less than | Numbers, Dates |
| Less than or equal | Numbers, Dates |
| Substring match | Text fields |
| Substring exclusion | Text fields |
| Matches any value in a comma-separated list | All field types |
| Matches none of the values in the list | All field types |
| Field is not null/empty | All field types |
| 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_pagedefaults to 10; maximum is 100.Paginated responses include
linksandmetaobjects 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
containson 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.