Search Orders

Applies to: Orders API

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

Link to section

Overview

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.

Link to section

Using a search filter

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, 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 the completed orders for three different customers:

Search orders

Link to section

Sorting the results

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

Link to section

Filtering and sorting within a date/time range

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_filtersort_field value
created_atCREATED_AT
updated_atUPDATED_AT
closed_atCLOSED_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.

Link to section

Search examples

Link to section

Search for orders within a specific date/time range

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

Link to section

Search for orders by fulfillment type and state

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.