Search Orders
You can use the SearchOrders
endpoint to search for orders using filter criteria that you specify. SearchOrders
also returns payments or refunds linked to orders, as well as V1 transactions. These are converted into Order
or OrderEntry
objects and returned as part of the search results.
To filter or sort your search results, call SearchOrders
with a SearchOrdersQuery object.
Your request must specify at least one location to search. Optionally, you can specify:
The order search criteria.
The sort order for the results.
Whether you want to receive the entire
Order
object or anOrderEntry
, which contains only theorder_id
,version
, andlocation_id
for the orders that match your query. Note that payments and refunds converted toOrderEntry
objects might not include aversion
.
When given no query criteria, SearchOrders
returns all results for the specified locations.
If you use DateTimeFilter
to filter for orders closed or updated within a time range, you must set the sort_field
field in SearchOrdersSort
to the same field. For example, if you set DateTimeFilter
to filter for CLOSED_AT
, then the sort_field
in SearchOrdersSort
must also be set to CLOSED_AT
.
If your DateTimeFilter
does not match the SearchOrdersSort
sort_field
, the endpoint throws an error.
For example, suppose a request has the following mismatched configuration:
SearchOrdersFilter
is configured to filter for bothOPEN
andCOMPLETED
orders.SearchOrdersSort
is configured to sort byCLOSED_AT
.
In this case, SearchOrders
is not able to sort any OPEN
orders and it returns an error.
The following is an example of a matched configuration:
SearchOrdersFilter
is configured to filter forCOMPLETED
orders.SearchOrdersSort
is configured to sort byCLOSED_AT
.
In this case, the sort and filter fields match so this call succeeds.
You can filter by any of the following fields:
state_filter
. Filter byOrderState
.date_time_filter
. Filter for results within a time range. If you use this filter, you must setSearchOrdersSort
to sort by the same field.fulfillment_filter
. Filter by the fulfillment type or state.source_filter
. Filter by the source of the order.customer_filter
. Filter by customers associated with the order.
If you set multiples of these fields, they are ANDed together to filter results.
Did you know?
You can search for items sold in a given time range by following these steps:
Call SearchOrders, specifying a
date_time_filter
in thequery
.With the returned list of
order_id
s, call RetrieveOrder or BatchRetrieveOrders and then filter the response to retrieve the returnedcatalog_object_id
s.With the
catalog_object_id
values, call RetrieveCatalogObject or BatchRetrieveCatalogObjects to returned the items sold in the given time range.
To sort your search results, your query should have a SearchOrdersSort
object, which contains two elements: sort_field
and sort_order
.
To sort the results, set sort_field
to one of these values:
CREATED_AT
- the date/time when the order was created.UPDATED_AT
- the date/time when the order was last updated.CLOSED_AT
- the date/time when the order was closed.
To determine the sort order, set sort_order
to one of these values:
ASC
- for oldest to newest.DESC
- for newest to oldest.
If you don't specify a SearchOrdersSort
in your query, the results are ordered by CREATED_AT
, from newest to oldest.
The following sample query returns all orders for a given location sorted by the CREATED_AT
timestamp from latest to earliest:
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.