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:
  • Access token: A valid access token. See the Authentication guide to learn how to obtain one.
  • 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, ranges, wildcards, and existence checks (_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:

​
Logical Operators

Combine multiple conditions using AND, OR, and NOT. Write them in upper case: a lower case and is searched as a word and quietly returns the wrong records. Conditions without an operator are joined with AND.

​
Quoting and Wildcards

Queries with spaces or quotes must be URL-encoded; curl --get --data-urlencode does this for you. Put quotes around values that contain spaces or the characters / or :. Without quotes, a space splits the value into two conditions and quietly returns the wrong records, and / or : fails with status 500. Use * as a wildcard for any characters:

​
Comparisons

Use comparison operators for numeric and date fields:

​
Ranges

Use square brackets for an inclusive range and * for an open end. Dates without a time need no quotes; a date with a time needs quotes. now works with date math:

​
Existence Checks

Check if a field exists:

​
Field Names

Use the field names of the search index. They mostly match the response, but not always:
  • Addresses are flat: deliveryAddressCountryIso2, not deliveryAddress.countryIso2.
  • On shipments and returns the address fields are deliveryAddress* and senderAddress*, not shipTo* and shipFrom* as in the response. Stored addresses use addressCity and addressCountry, not city and country.
  • Lists inside a record use a dot: shipments.trackingNumber.
A condition on a wrong field name gives no error. It matches nothing, so on its own it returns no records, with OR the other conditions still return records, and under NOT it drops nothing, which can widen the result to every record. The query parameter of each endpoint in the API Reference lists its fields with examples.

​
Examples

​
Example: Filtering Orders by Status and Date

Filter orders with status “PROCESSING” created before a specific date:

​
Example: Filtering Orders with Shipments

Filter orders that have shipments with tracking numbers:

​
Example: Filtering Shipments by Tracking Number

Filter shipments by tracking number:
All fields stored in Elasticsearch can be used in queries. The exact fields available depend on the endpoint. The query parameter of each endpoint in the API Reference lists its main fields.

​
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:

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