The SearchOrders endpoint lets you find orders that match your filtering criteria. For example, you can search for orders created within a specific time range, requested by a particular customer, or to be delivered to the customer.
Your request must include one or more location_ids
. SearchOrders
only returns the orders for those locations.
You can optionally provide a SearchOrdersQuery in your request, which consists of the following:
filter
- Narrows the search results using the criteria you specify.sort
- Returns the search results in ascending or descending order.
By default, SearchOrders
returns the matching Order
objects in their entirety. You can set return_entries
to true
and receive short summaries of the orders instead (OrderEntry objects).
Note
The SearchOrders
endpoint can potentially return a large number of orders, depending on your search criteria, so you might need to process the results one page at a time. For more information, see Pagination.
The filter
parameter of a query
lets you narrow the results from SearchOrders
. Note that if you use more than one filter
in a query
, the results from all of the filters are ANDed together.
The following filters are available:
customer_filter
- Orders that are associated with a specific customer.fulfillment_filter
- Orders that are picked up, shipped, or delivered. You can search for orders that are in a particular state in the fulfillment process.source_filter
- Orders that originate from a particular source. For example, the name of the application that created the order.state_filter
- Orders that are in specific states:OPEN
,DRAFT
,COMPLETED
, orCANCELED
.date_time_filter
- Orders where an event occurred during a particular time period. For more information, see Filtering and sorting within a date/time range.
The following SearchOrders
request returns the completed orders for three different customers:
Search orders
The sort
parameter of a query
returns the search results in a sorted order. There are two parameters available:
sort_field
- The date and time when an event occurred. Valid values are as follows:CREATED_AT
- The timestamp when the order was created, which is the default.UPDATED_AT
- The timestamp when the order was last updated.CLOSED_AT
- The timestamp when the order was closed.
sort_order
- The order in which results are returned. Valid values are as follows:DESC
- Newest to oldest, which is the default.ASC
- Oldest to newest.
If you don't specify a SearchOrdersSort
in your query, the results are ordered by CREATED_AT
, from newest to oldest.
The following SearchOrders
request returns the delivery orders that successfully completed:
Search orders
Every Order
object contains several timestamps, which represent events that occur during that order's lifecycle. SearchOrders
can return orders within a date/time range for one of these events. You can specify a date_time_filter
for one of the following event types:
created_at
- The timestamp when the order was created.updated_at
- The timestamp when the order was last updated.closed_at
- The timestamp when the order was closed.
Each event type has start_at
and end_at
fields to specify the date/time range for the filter. You must provide these in RFC 3339 timestamps format.
If you want the results to be sorted by event type, you must provide a sort_order
that matches the date_time_filter
.
date_time_filter | sort_field value |
---|---|
created_at | CREATED_AT |
updated_at | UPDATED_AT |
closed_at | CLOSED_AT |
Important
If you specify the CLOSED_AT
sort order, you must use a state_filter
in your request. You must set state_filter
so that it matches COMPLETED
orders, CANCELED
orders, or both.
The following request returns orders that were completed during a specific time period. The orders are sorted by the closed_at
timestamp, from oldest to newest.
Search orders
The following request returns orders that are prepared and ready for pickup:
Search orders
In the response, each order contains a fulfillments
array with details about the fulfillment.
{ "orders": [ { "id": "cpdycBiu7JlxPwOvksoIB0hpCWAZY", ... "fulfillments": [ { "uid": "dgjWH3mMEVL50YKhIJ267C", "type": "PICKUP", "state": "PROPOSED", "pickup_details": { "pickup_at": "2023-05-24T19:31:26.515Z", "schedule_type": "ASAP", "recipient": { "display_name": "John Q. Customer" }, "prep_time_duration": "P0DT0H30M0S" } } ] } ... ] }