Product Query reference #

Product Query reads one published model in one Product Instance. Filters use indexed field values and relationships, and all where clauses are combined with AND.

Use the generated contract for the model's available field keys. Unknown, unpublished, non-stored, or unsupported field uses return a validation error.

Build a query #

A query can contain:

json

{
  "where": [
    { "field": "status", "op": "eq", "value": "declined" },
    {
      "field": "occurred_at",
      "op": "gte",
      "value": "2026-08-01T00:00:00Z"
    }
  ],
  "order_by": [
    { "field": "occurred_at", "direction": "desc" }
  ],
  "select": ["occurred_at", "status", "amount"],
  "page_size": 100,
  "cursor": null,
  "include_total": false,
  "include_archived": false
}

The response envelope contains results, next_cursor, page_size, and model. It contains total_count only when include_total is true.

Use typed filter operators #

All filterable fields support eq, neq, is_null, and not_null. Additional operators depend on the published field type:

string, text, enum, and system ID fields support in, contains, and prefix
integer, decimal, and money fields support in, gt, gte, lt, and lte
date fields support in, gt, gte, lt, and lte
datetime fields support gt, gte, lt, and lte, but not in
record and native references support in; they do not support range or text operators
boolean fields use equality and null operators

in requires a list and accepts at most 50 values. Product Query accepts at most 16 filter clauses.

Dates, datetimes, numbers, and booleans are validated and coerced according to their field type. A field type that has no query index is not filterable.

Select fields #

Use select to project the returned record data and field definitions to a list of published field keys. Record identity and envelope metadata remain in the response.

Projection reduces response size; it is not an authorisation mechanism. Permissions and customer visibility are enforced before projection.

Order results #

Each ordering entry has a published field and a direction of asc or desc. Product Query accepts at most three requested ordering fields.

The default order is updated_at descending. created_at, updated_at, and public_id are record ordering fields. Stored non-reference fields can also be ordered. Reference fields cannot be used for ordering.

The service adds public_id as a deterministic tie-breaker when it is not already present.

Follow cursor pagination #

The default page size is 50 and the maximum is 200. A larger requested value is capped at 200.

Pass next_cursor unchanged as the next request's cursor. The signed cursor is bound to the Product Instance, model, filters, ordering, and archived selection. Editing it or applying it to a different query returns a validation error. Do not derive offsets from it.

Request totals only when needed #

Set include_total to request total_count for the complete filtered result before cursor pagination. Totals require an additional count query, so omit them from paging loops that do not display a total.

Include archived records deliberately #

Active records are the default. Set include_archived to include both active and archived records when the client and model permit the read. Inspect each record's archived_at value to distinguish them.