> For the complete documentation index, see [llms.txt](https://docs.claret.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claret.app/api-guide/filtering-and-sorting.md).

# Filtering & Sorting

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**).

```bash
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`                              |

{% hint style="info" %}
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.
{% endhint %}

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).

```bash
# 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.

```bash
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).

{% hint style="info" %}
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.
{% endhint %}

## Putting it together

Filters, sorts, includes, and [pagination](/api-guide/pagination.md) compose in a single request:

```bash
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](/api-guide/pagination.md) — paging through filtered results.
* The **API Reference** — allowed filters, sorts, and includes per endpoint.
* [Error Reference](/api-guide/errors.md) — resolving `422` from unsupported parameters.