Skip to main content

Filtering & Sorting

List endpoints support filtering and sorting where documented.

Only supported parameters are accepted, and results are determined exclusively by the parameters provided in the request.

Conventions​

Explicit filters​

  • Only supported query parameters are accepted.
  • Unknown parameters return 400 Bad Request.
  • Multiple filters can be combined and are applied using AND logic.
GET /api/v1/reviews?type=product&product_id=2532&status=published
info

When multiple filters are provided, all conditions must match.

Exact matching​

  • String filters (like locale) are exact match.
  • Partial matches and fuzzy searching are currently not supported.

Pagination compatibility​

Filtering and sorting work with pagination (page, per_page). Pagination metadata (total results, total pages, prev/next links) reflects the filtered dataset and preserves the same query parameters.

See Pagination.

Filtering details​

Multiple values​

Some filters support multiple values. When multiple values are provided for the same parameter, they are evaluated using OR logic.

Values must be provided as a comma-separated list.

GET /api/v1/reviews?rating=4,5&status=published

This matches reviews with a rating of 4 OR 5. Any additional filters in the request are still applied using AND logic.

Date and time range filters​

Date range filters use ISO 8601 datetimes format.

The API accepts:

  • Full datetimes (for example, 2025-01-31T23:59:59Z)
  • Date-only values (for example, 2025-01-31)

Both bounds are inclusive.

If the time component is omitted, date-only values are interpreted as full-day ranges.

For any date range filter:

  • The *_from parameter is interpreted as 00:00:00 (start of day)
  • The *_to parameter is interpreted as 23:59:59 (end of day)
GET /api/v1/reviews?created_at_from=2025-01-01&created_at_to=2025-01-31

This is equivalent to:

GET /api/v1/reviews?created_at_from=2025-01-01T00:00:00Z&created_at_to=2025-01-31T23:59:59Z

Sorting​

Use the sort query parameter to control the order of results.

Each endpoint defines a default sort order, which is applied when sort is not specified.

Sort values​

Sort values follow the <field>_<direction> format, where:

  • asc sorts results in ascending order
  • desc sorts results in descending order

Supported sort values are endpoint-specific.
For example, on the List Reviews endpoint, the following values are available:

  • created_at_desc (default)
  • created_at_asc
  • rating_desc
  • rating_asc
GET /api/v1/reviews?status=published&sort=rating_desc
note

When sorting by translatable name fields (e.g. name_asc, name_desc), ordering uses the effective locale of the request.

  • If a single locale is provided, sorting uses that locale.
  • If multiple locales are provided, sorting uses the first locale in the list.
  • If no locale is specified, the default system locale is used.

This rule applies consistently across all endpoints supporting name-based sorting.

Validation & errors​

Query parameters are validated strictly and return 400 Bad Request in these cases:

  • Unknown query parameters
  • Invalid values (e.g., rating out of range, invalid datetime format)

For the error response format, see Error Handling and Rate Limits.

Examples​

Product reviews for a specific product (published)​

GET /api/v1/reviews?type=product&product_id=2532&status=published

Published reviews with rating 4 or 5, oldest first​

GET /api/v1/reviews?rating=4,5&status=published&sort=created_at_asc

Store reviews in a date range for a locale​

GET /api/v1/reviews?type=store&locale=en-GB&created_at_from=2025-01-01T00:00:00Z&created_at_to=2025-01-31T23:59:59Z

For endpoint-specific parameter definitions, check the API Reference.