Entity Query Parameters and Pagination

Many API endpoints that return lists support a standard set of query parameters for filtering, sorting, pagination, and including related entities. This page explains how to use all supported query options and how paged responses work.

Supported Query Parameters

• where – Filter results (JSON)
• order – Sort results (comma-separated string)
• limit – Number of items per page
• page – Page number (starting at 1)
• include – Include related entities (comma-separated paths)

Filtering with "where"

The where parameter accepts a JSON object describing filters. It may be provided as raw JSON or URL-encoded JSON.

If the JSON cannot be parsed, the API responds with 400 Bad Request.

Exact Match

GET /places/:placeId/orders?where={"status":"Closed"}

IN Filters (Arrays)

If a value is an array, it is treated as an IN condition.

GET /places/:placeId/orders?where={"status":["Closed","Cancelled"]}

Wildcard Filters

Strings containing * are treated as wildcard searches and mapped to SQL LIKE (case-insensitive).

GET /places/:placeId/orders?where={"customer_name":"John*"}

Range Filters (BETWEEN)

Objects containing from and to are treated as range filters.

GET /places/:placeId/orders?where={"created":{"from":1700000000,"to":1702592000}}

Logical Filters ($and / $or)

$or example:

GET /places/:placeId/orders?where={"$or":[{"status":"Closed"},{"status":"Rejected"}]}

$and example:

GET /places/:placeId/orders?where={"$and":[{"status":"Closed"},{"type":"Delivery"}]}

Combined example:

GET /places/:placeId/orders?where={"$and":[{"type":"Delivery"},{"$or":[{"status":"Closed"},{"status":"Cancelled"}]}]}

Sorting with "order"

The order parameter controls result ordering.

• Prefix a field with - for descending order
• Fields without a prefix are sorted ascending

Default ordering:

created DESC

Examples

GET /places/:placeId/orders?order=created

GET /places/:placeId/orders?order=-created

GET /places/:placeId/orders?order=-created,status

Pagination

Some endpoints return paged results. When pagination is supported, paging metadata is included in the response body.

Request Parameters

• limit – Number of results per page
  • Default: 10
  • Maximum: 10 (endpoint-dependent)
• page – Page number to retrieve
  • Starting index: 1

Example Request

GET /places/:placeId/orders?limit=10&page=2

Pager Object in Responses

Paginated responses include a pager object describing the current result set.

{
  "pager": {
    "total_items": 250,
    "current_page": 2,
    "total_pages": 25,
    "items_per_page": 10
  },
  ...
}

Pager Fields

• total_items – Total number of matching items
• current_page – Current page number (starting at 1)
• total_pages – Total number of pages available
• items_per_page – Number of items returned per page

Paging Behavior

• If paging parameters are omitted, defaults are used
• If page exceeds total_pages, an empty result set may be returned
• The pager object is only included for endpoints that support pagination

Including Related Entities with "include"

The include parameter allows related entities to be included in the response. It is a comma-separated list of association paths.

Examples

GET /places/:placeId/orders?include=table

GET /places/:placeId/orders?include=payments,account

GET /places/:placeId/orders?include=deliveryLocation

• Only associations defined on the model can be included
• Invalid association paths are ignored
• Nested includes use dot notation (e.g., account.tier)

URL Encoding

Because the where parameter contains JSON, URL encoding is often required. The API attempts to automatically decode encoded parameters.

GET /places/:placeId/orders?where=%7B%22status%22%3A%22Closed%22%7D

Combined Example

Example using filtering, sorting, pagination, and includes together:

GET /api/v1/orders
?where={"$and":[
  {"type":"Delivery"},
  {"status":["Closed","Cancelled"]},
  {"created":{"from":1700000000,"to":1702592000}}
]}
&order=-created
&limit=10
&page=1
&include=deliveryLocation,payments

Error Handling

Invalid where or order parameters result in a 400 response.

{
  "message": "Invalid JSON in filters parameter",
  "error": "Unexpected token ..."
}

Summary

• where – JSON-based filtering with ranges, wildcards, and logical operators
• order – Comma-separated sorting with optional descending prefixes
• limit / page – Pagination controls (page starts at 1)
• pager – Response metadata for paged endpoints
• include – Include related entities via association paths