Filtering & Sorting

Query parameter reference for filtering, sorting, and including related data.

Every list endpoint accepts a common set of query parameters to narrow, order, and expand its results. The specific keys each endpoint allows are listed on that endpoint's reference page; this guide covers the shared syntax.

Filtering

Filters use bracket syntax: filter[<key>]=<value>. Combine multiple filters by repeating the parameter; they are applied together (logical AND).

curl "https://plan.claret.app/{tenant}/api/v1/items?filter[name]=Chardonnay&filter[description]=2024" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Filter types

Type	Behavior	Example
Name / text	Partial, case-insensitive match	filter[name]=Chard
ID	Exact match	filter[item_id]=42
Related name	Partial match on a related record's name	filter[customer_group_name]=North
Date range	Paired _from / _to bounds (inclusive, YYYY-MM-DD)	filter[date_from]=2026-01-01&filter[date_to]=2026-03-31
Numeric range	Paired _from / _to bounds	filter[quantity_from]=100&filter[quantity_to]=500
Boolean	0 or 1	filter[is_crop_location]=1

Date and numeric filters are bounds, not equality. Use filter[date_from] and filter[date_to] with the same value to match a single day.

Filtering on an unsupported key returns 422 with the allowed keys. Each endpoint's reference page lists exactly what it accepts.

Sorting

Use the sort parameter with a field name. Prefix with - for descending order. Sort by multiple fields with a comma-separated list (applied left to right).

# Newest first, then by name ascending
curl "https://plan.claret.app/{tenant}/api/v1/supply-plans?sort=-date,quantity" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Syntax	Meaning
sort=name	Ascending by name.
sort=-date	Descending by date.
sort=-date,name	Descending by date, ties broken ascending by name.

Most endpoints allow sorting on id, created_at, updated_at, and a few domain fields (such as name, date, or quantity). Sorting on an unsupported field returns 422.

Including related data

Use include to embed related records in the response, avoiding extra round-trips. Pass a comma-separated list of relationship names.

curl "https://plan.claret.app/{tenant}/api/v1/sales-data?include=saleType,itemCustomerGroup,uom" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Each included relationship is nested inside its parent record in the data payload. The set of allowed includes is endpoint-specific; some includes expand into nested relations (for example, include=itemCustomerGroup on sales data returns the item and customer group within it).

Including relationships does not change the credit cost of a request. Prefer one request with the includes you need over several requests fetching related records separately.

Putting it together

Filters, sorts, includes, and pagination compose in a single request:

curl "https://plan.claret.app/{tenant}/api/v1/supply-plans?\
filter[supply_type_name]=Crush&\
filter[date_from]=2026-01-01&\
sort=-date&\
include=supplyType,uom&\
per_page=500" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Related documentation

• Pagination — paging through filtered results.

• The API Reference — allowed filters, sorts, and includes per endpoint.

• Error Reference — resolving 422 from unsupported parameters.