Skip to main content
This guide explains how to use query parameters to filter and search data across different endpoints in the Quivo API. Many endpoints support a query parameter that allows you to filter results using specific syntax.

​
Overview

The Quivo API provides query parameters on many endpoints that let you filter and search data efficiently. The query parameter supports specific syntax for filtering across multiple fields, allowing you to build complex search queries without making multiple API calls.
For information about pagination and sorting, which work together with query parameters, see the Pagination & Idempotency reference.

​
Prerequisites

Before you start, make sure you have:
  • Session token: A valid session token. See the Authentication guide to learn how to obtain one.
  • API key: Your static API key provided by Quivo.
  • Understanding of endpoint structure: Familiarity with the endpoints you want to query. See the API Reference for endpoint documentation.
All API examples in this guide use ${BASE_URL} as a placeholder. Replace it with the correct base URL configured for the correct environment. For more information see Environments page.

​
Understanding the Query Parameter

The query parameter is available on many GET endpoints in the Quivo API. It accepts a search query string that filters results using Elasticsearch query syntax. Key characteristics:
  • The query parameter uses Elasticsearch query syntax directly (queries are executed directly against Elasticsearch)
  • All fields stored in Elasticsearch can be used in queries
  • You can combine query parameters with sorting and pagination parameters
  • Supports logical operators (AND, OR, NOT), comparisons, and functions (for example, exists)
The Quivo API uses Elasticsearch internally to process queries. The /ping endpoint confirms this by checking both database and Elasticsearch connectivity. The query parameter executes queries directly against Elasticsearch, so you can use standard Elasticsearch query syntax.

​
Finding Query Support

Not all endpoints support the query parameter. To determine if an endpoint supports querying, see the detailed endpoint documentation in the API Reference section

​
Common Endpoints with Query Support

The following endpoints are known to support the query parameter:
  • Articles: GET /articles - Search articles by various criteria
  • Orders: GET /orders - Filter orders by status, date, or other fields
  • Shipments: GET /shipments - Search shipments by tracking number, status, or other criteria
  • Items: GET /items - Filter inventory items by warehouse, SKU, or other fields
  • Inbounds: GET /inbounds - Search inbound shipments by status or other criteria
  • Bundles: GET /bundles - Filter product bundles by SKU or other criteria

​
Query Syntax

The query parameter uses Elasticsearch query syntax. Here are some common patterns:

​
Basic Field Matching

Filter by a specific field value: 
fieldName: "value"

​
Logical Operators

Combine multiple conditions using AND, OR, and NOT: 
(field1: "value1" AND field2: "value2")
(field1: "value1" OR field2: "value2")
NOT field1: "value1"

​
Comparisons

Use comparison operators for numeric and date fields: 
fieldName: <value    # Less than
fieldName: >value    # Greater than
fieldName: <=value   # Less than or equal
fieldName: >=value   # Greater than or equal

​
Existence Checks

Check if a field exists: 
exists: fieldName

​
Examples

​
Example: Filtering Orders by Status and Date

Filter orders with status “PROCESSING” created before a specific date: 
curl -X GET "${BASE_URL}/orders?query=(orderStatus: \"PROCESSING\" AND created:<2026-01-01)" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

​
Example: Filtering Orders with Shipments

Filter orders that have shipments with tracking numbers: 
curl -X GET "${BASE_URL}/orders?query=(orderStatus: \"PROCESSING\" AND (exists: shipments.trackingNumber))" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

​
Example: Filtering Shipments by Tracking Number

Filter shipments by tracking number: 
curl -X GET "${BASE_URL}/shipments?query=trackingNumber:<TRACKING_NUMBER>&sort=created:desc&pageSize=50" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"
All fields stored in Elasticsearch can be used in queries. The exact fields available depend on the endpoint and what data is indexed in Elasticsearch. If you need a complete list of queryable fields for a specific endpoint, contact Quivo support.

​
Combining Query with Other Parameters

You can combine the query parameter with other parameters for more precise results:
  • Sorting: Use the sort parameter to order results (for example, sort=created:desc)
  • Pagination: Use page, pageSize, and searchAfter for pagination
  • Multiple filters: The query syntax may support combining multiple filters
Example combining query, sort, and pagination: 
curl -X GET "${BASE_URL}/articles?query=<SEARCH_TERM>&sort=created:desc&page=1&pageSize=20" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

​
Where to go next

Now that you understand how to use query parameters, continue with these guides:

Manage Products

Learn how to search and filter products using query parameters.

Manage Shipments

See examples of querying shipments by tracking number and other criteria.