The Order Search feature is intended for merchants to perform search requests on a high number of Orders in a Project. It is not intended for searching through the customer's order history in a storefront application.
The Order Search API does not return the resource data of the matching Orders. Instead, it returns a list of Order IDs, which can then be used to fetch the Orders by their ID.
Since the response also contains the version of the matching Order, it allows you to:
- keep a cache of Orders
- compare version numbers to detect outdated Orders
- detect if the search index for an Order is outdated and react on that (for example by showing a warning, or trigger a rebuild of the search index).
Activation of the feature The Order Search feature is not active for the Project by default. Before first use, indexing has to be activated either
- via API using the Change Order Search Status update action on the Project.
- via contacting us on the Support Portal and provide the region, project key(s), and use case(s).
Once the Project setting has been changed, the indexing of all Orders existing in the Project will start and the Search Orders endpoint will become fully functional soon after.
Automatic deactivation The Order Search index for a Project will be deactivated automatically if there have been no calls against the Search Orders endpoint within the last 30 days. Indexing can be reactivated again with one of the options listed above.
Unique identifier of the Order.
Current version of the Order.
The higher the value is, the more relevant the hit is for the search request.Maximum:
Region in which the Project is hosted.
The Order search query.
Array of OrderSearchSorting
Controls how results to your query are sorted. If not provided, the results are sorted by relevance in descending order.
The maximum number of search results to be returned.Default:
The number of search results to be skipped in the response for pagination.Default:
A query consists of:
- A compound expression wrapper, like
- A query expression, like
fullText. You can use more than one query expression per query.
- A set of query fields. The
valuefields are required, but there are other optional fields.
This query is searching for all orders which have
banana in their
lineItems.name and are in the
This can be seen as:
The result will be all documents where
lineItems.name.en contains 'banana' and the store name is 'fruit_store', sorted descending (
The result will be limited to the first 50 hits.
The outermost layer of the query is a compound expression. This expression specifies how the composition of the sub-expressions is evaluated. Sub-expressions can be query expressions or compound expressions.
Following compound expressions are currently supported:
|only matches documents that match all sub-expressions.|
|only matches documents where at least one of the sub-expressions is matched.|
|only matches documents that do not match any of its sub-expressions.|
|Matching documents of a query are checked for their relevancy to the search. The relevancy is expressed by an internal score. All expressions except filter expressions contribute to that score. All sub-expressions of a filter are implicitly connected with an |
A compound expression can only be used one time on the same level of composition.
For example, this composition of two
and expressions is not supported: Z = (A
using only one
and expression, like: X = (A
and B), is allowed.
Using a different compound expression is allowed too, like for: Y = (A
Z can still be specified by (X
and C) since X is a compound expression on a different level then.
A query expression contains:
- for localized texts: a
languagevalue is an IETF language tag.
The index is calculated with languages defined in the Project. It is not possible to find documents with a non-defined language.
field can have any of the searchable Order fields, like
country including fields of nested objects like LineItems (
lineItems.productId) or ShippingMethods (
Example of a query finding orders with a specific price:
Searchable Order fields
It is possible to search in the order's custom fields.
customType needs to be specified in the query.
Currently, the following types are supported.
If you want to search for a date in a custom field SetType with many dates, a query might look like this:
customTypes support the following query expressions, where
SetType support the same expressions as the type inside the
|StringType, EnumType, DateType, TimeType, DateTimeType||✓||✓||✓||✓||✓|
Query expression types
Performs a full text search of the field.
fullText queries have the option to pass
mustMatch on how multiple terms should be combined.
mustMatch can either be
all (the default is
If you search for 'yellow car' the search will find documents that contain both 'yellow' and 'car' by default.
When you now pass
mustMatch the search will find documents that contain either 'yellow' or 'car'.
fullText search will only return Orders for which the terms match completely.
If you need partial matches, the prefix search would be the better approach.
fullText query performs a full-text search:
Searches for exact values only. If you provide a value of
yellow car, a field with
the best yellow car will not match.
This means the value you provide for searching must exactly match the value in the order search.
exact queries have the option to treat the search term
exact query only matches exact values:
Searches the field specified for ones that begin with the prefix specified.
prefix queries have the option to treat the search term
prefix query only matches values that start with the given one:
Note that searching for
yell ca in the value
yellow car will not lead to a match, all terms need to form one prefix, you would need to search for
yellow c to match
range query only matches values between the specified boundaries and is useful for restricting the search query to certain time frames or ranges of numerical values. The interval may also be open by omitting the upper or lower boundary value.
Example query for Orders last modified between two specific dates:
wildcard query matches documents that have fields matching the specified wildcard expression.
In wildcard expression, the following characters have a special meaning:
*for one or more characters
?for exactly one character.
wildcard queries have the option to treat the search term
It is even possible to use more than one wildcard in one term.
wildcard queries as well have the option to treat the search term
Wildcard expression are quite expensive to calculate. Prefer a prefix expression if this is suitable for your use-case.
exists query matches documents that have a field with a non-null value:
When you provide more than one query expression to a query, the
boost field makes the results that match one particular query more relevant than the results that match the others.
Example query: Documents that have
butter in the
lineItems.name field are scored as more relevant than those that have
butter in their
Types of fields
What query expression type can be used on what type of field?
Specifics for phoneField
When searching on a
phoneField type of field all non numeric characters are ignored.
For example, a query of type fullText for
(783) 627-3740 will also match
The same applies to prefix queries. Special characters are only taken into account when performing queries of type exact.
Sorting allows you to control how results to your query are sorted.
If no sorting is specified, the results are sorted by relevance in descending (
Example query (sorts the results ascending by
If you sort by a field in an array (like
customLineItems.name) you can optionally pass a sort mode.
This is relevant because a single order can have multiple lineItems and thus multiple
That means that there might not be a single value to sort on, but multiple.
Using the sort mode we can choose which of the values in the array to use for sorting or how to aggregate them.
The default sorting mode is
Following four sort modes are provided:
min- Use the minimum of all available values
max- Use the maximum of all available values
avg- Use the average of all available values
sum- Use the sum of all available values.
Example query (Using the
min sort mode, will sort using the min
customLineItems.name in descending order):
In case the above sort modes are not enough to specify exactly which document or aggregation you want to sort on, you can use a sort
Note that you can only filter on the same parent field you sort by. In this case on the root of the order.
If you realize the Order Search API does not contain the latest Orders, you can trigger a rebuild of the search index. This service is provided on a GraphQL endpoint by submitting a specific reindex mutation.
OAuth 2.0 Scopes:
This mutation returns following indexing job IDs:
indexingJobIdis the ID of a new indexing job.
existingIndexingJobIdis the ID of an already running job making progress.
Check indexing progress
For each indexing job ID you can check the status of the respective jobs like so:
OAuth 2.0 Scopes:
Stop indexing jobs
You can stop the indexing of all Orders with following mutation:
OAuth 2.0 Scopes:
The response contains the
status of the indexing job.
You can access the GraphQL endpoint with following URL:
The endpoint accepts HTTP POST requests with following fields in a JSON body:
query- String - GraphQL query as a string
variables- Object - Optional - containing JSON object that defines variables for your query
operationName- String - Optional - the name of the operation, in case you defined several of them in the query
To explore the GraphQL endpoint, you can use an interactive GraphiQL environment with a web browser, accessible through the following URL:
Check search index
To check whether a search index exists for the Project's Orders the following endpoint can be used.
OAuth 2.0 Scopes:
Response status codes:
200- the index exists and the Search Orders endpoint can be used.
404- the index does not exist and the Search Orders endpoint returns
On the GraphQL endpoint you can use following query:
The query response contains the following fields indicating the status of the search index:
searchableIndexExists- the index exists and Orders can be searched.
newInProgress- the index is being created by a job. Use the
reIndexAllOrdersmutation to get the job ID.
Find below an example for a
FetchIndicesExists query to be executed as cURL command: