Shopify API search syntax
This page provides information on the syntax for searching text fields.
The same search query syntax is used across Shopify as an interface to search functionality. This includes the storefront, admin, mobile apps, customer group queries, Admin API, and Storefront API. For the APIs, the specific resources that can be queried are defined in the reference documentation.
Search query grammar overviewAnchor link to section titled "Search query grammar overview"
A string query is a text search made up of terms, connectives, modifiers, and comparators. The search grammar rules defined here can be built into larger structures as defined by the search query syntax.
The search grammar is expressed similarly to EBNF and uses the following baseline terminal symbols:
||Any sequence of space, tab, or newline characters.|
||Any sequence of non-whitespace, non-special characters. For more information, refer to Special characters.|
||Any name, or any quoted string (single or double quotes are both permitted). Date values must be a string surrounded by quotes.|
A query is one or more terms separated by whitespace and optionally by single connectives. A query may have optional leading and trailing whitespace.
ConnectivesAnchor link to section titled "Connectives"
When a connective is not specified between two terms,
AND is implied.
query=state:enabled OR state:disabled
A term consists of an optional modifier, followed either by a subquery (enclosed in parentheses) or a value with an optional name-and-comparator.
query=-first_name:Bob AND orders_count:>3 orders_count:<=4
Supported modifiers are
- with no following whitespace, or
NOT followed by whitespace. Both mean the same thing.
ComparatorsAnchor link to section titled "Comparators"
The following comparators are supported for search queries:
Search query syntaxAnchor link to section titled "Search query syntax"
Shopify search query syntax is based on the defined grammar and enables the following search behavior.
Term searchAnchor link to section titled "Term search"
A term search is a case-insensitive search of all the fields in a document.
The following query makes a case-insensitive search for both "bob" AND "norman":
Field searchAnchor link to section titled "Field search"
Field searches apply to terms in specific fields.
The following query searches for "Bob" in the
first_name field AND "27" in the
The value must immediately follow the field with no whitespace.
first_name: Bob searches for the terms "first_name" and "Bob".
Range searchAnchor link to section titled "Range search"
A range search specifies a range of values to search against. Supported operators are
The following query matches documents where the
orders_count field is greater than 16 and less than or equal to 30:
:) is specified by
orders_count:=16 searches for the term "=16" in the
A NOT query excludes documents that include the specified value.
The following queries excludes documents that include the term "bob":
The NOT operator must be capitalized to execute a NOT query, and only applies to the specified space-separated term or query.
- must precede the field, value, or subquery. For example,
-field:value -value -(subquery).
Boolean operatorsAnchor link to section titled "Boolean operators"
Boolean operators allow terms to be combined through logic operators.
The following query searches for documents that must have the term "Shopify" and have at least one of the terms "bob" or "norman":
query=bob OR norman AND Shopify
The following query is equivalent to the query above, since OR has a higher operator precedence than AND:
query=bob OR norman Shopify
An explicit AND operator is not needed between "bob OR norman" and "Shopify" because the AND is the default boolean operator between terms or queries.
You can use parentheses to group clauses to form subqueries.
The following query searches for disabled customers with "sale shopper" or "VIP" tags:
query=state:disabled AND ("sale shopper" OR VIP)
Phrase queryAnchor link to section titled "Phrase query"
A phrase is a group of words surrounded by double quotes.
The following query searches for the term "bob" followed immediately by the term "norman" in the
Phrase queries can be used without the
query field. For example,
Prefix queryAnchor link to section titled "Prefix query"
A prefix query matches documents containing terms that begin with a specified set of characters.
The following query searches for all the terms that begin with the prefix "norm", such as "norman":
Exists queryAnchor link to section titled "Exists query"
An exists query matches documents with a non-null value in the specified field.
The following query searches for non-null values in the
The query can be combined with a NOT query to find fields missing a value. For example,
Special charactersAnchor link to section titled "Special characters"
You can escape the following special characters using backslash escaping:
Names can include the characters
" but cannot start with them. Names can include escaped characters using backslash escaping.
This section provides examples of how you can use the Shopify API search syntax.
Using Anchor link to section titled "Using created_at"
List 5 products that were added to a store on October 21st, 2020.
Using Anchor link to section titled "Using title"
List 5 products with the name "Caramel Apple".
Using Anchor link to section titled "Using OR and a range"
OR and a range
List 5 products with the name "Caramel Apple", or products that have an inventory of over 500 items and less than or equal to 1000 items.