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 an OrderEntry, which contains only the order_id, version, and location_id for the orders that match your query. Note that payments and refunds converted to OrderEntry objects might not include a version.

When given no query criteria, SearchOrders returns all results for the specified locations.

Link to section

Important note about filtering orders by time range

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 both OPEN and COMPLETED orders.

• SearchOrdersSort is configured to sort by CLOSED_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 for COMPLETED orders.

• SearchOrdersSort is configured to sort by CLOSED_AT.

In this case, the sort and filter fields match so this call succeeds.

Link to section

Filtering

You can filter by any of the following fields:

• state_filter. Filter by OrderState.

• date_time_filter. Filter for results within a time range. If you use this filter, you must set SearchOrdersSort 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.

curl https://connect.squareupsandbox.com/v2/orders/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "location_ids": [
      "{LOCATION_ID}"
    ],
    "query": {
      "filter": {
        "date_time_filter": {
          "closed_at": {
            "start_at": "2018-03-04T21:54:45+00:00",
            "end_at": "2019-03-04T21:54:45+00:00"
          }
        },
        "state_filter": {
          "states": [
            "COMPLETED"
          ]
        }
      },
      "sort": {
        "sort_field": "CLOSED_AT",
        "sort_order": "DESC"
      }
    }
  }'

Link to section

Sorting

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.

Link to section

Sample sort query

The following sample query returns all orders for a given location sorted by the CREATED_AT timestamp from latest to earliest:

curl https://connect.squareupsandbox.com/v2/orders/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "return_entries": true,
    "location_ids": [
      "{LOCATION_ID}"
    ],
    "query": {
      "sort": {
        "sort_field": "CREATED_AT",
        "sort_order": "ASC"
      }
    }
  }'