Search Orders

Applies to: Orders API

Learn about searching orders, how filtering and sorting works, and about filtering orders by a time range.

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 that customer.

Your request must include one or more location_ids. SearchOrders only returns the orders for those locations.

You can provide a SearchOrdersQuery in your request, which consists of these properties:

• filter - Restricts search results to your filter criteria.
• sort - Returns the search results sorted by one of three Order timestamps 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).

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 the filters are ANDed together.

The following filters are available:

• customer_filter - Orders for specified customers.
• fulfillment_filter - Orders in selected fulfillment states and of selected fulfillment types.
• source_filter - Orders whose Order.source.name matches any string you add to the source_filter.
• state_filter - Orders in specific states: OPEN, DRAFT, COMPLETED, or CANCELED.
• 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 orders originated by the "MyOrderApp" application, whose pickup fulfillment is completed and sorted by the date/time they were created (in ascending order):

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 SearchOrdersSortField in your query, the results are ordered by CREATED_AT, from newest to oldest.

The following SearchOrders request returns orders that have been delivered:

Every Order object contains timestamps that represent events occurring in an order's lifecycle. SearchOrders can return orders within a date/time range for any of these events. You can specify a date_time_filter for any 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.

Multiple event type filters are ANDed together in the query. Only orders whose event timestamps occur within all time/date ranges are returned. 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.

The following request returns orders sorted by closed date, created between May 18 and 21, and completed between May 30 and 31:

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.