Search Orders

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).

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:

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:

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.

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.

The following request returns orders that are prepared and ready for pickup:

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"
          }
        }
      ]
    }
    ...
  ]
}