Orders API

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.

  • Specify 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.

Important note about filtering orders by time range Permalink Get a link to this section

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.

Filtering Permalink Get a link to this section

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 multiple of these fields, they are ANDed together to filter results:

Search Orders
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
curl https://connect.squareupsandbox.com/v2/orders/search \
  -X POST \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "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"
      }
    }
  }'

Sorting Permalink Get a link to this section

To sort your search results, your query should have a SearchOrdersSort object. SearchOrdersSortcontains two fields: sort_field and sort_order.

You can sort your results by setting the sort_field to:

  • The CREATED_AT field.

  • The UPDATED_AT field.

  • The CLOSED_AT field.

You can determine the sort order by setting sort_order to ASC for latest to earliest or to DESC for earliest to latest.

By default, results are returned in order of the CREATED_AT date from earliest to latest.

Sample sort query Permalink Get a link to this section

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

Search Orders
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/orders/search \
  -X POST \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "return_entries": true,
    "query": {
      "sort": {
        "sort_field": "CREATED_AT",
        "sort_order": "ASC"
      }
    }
  }'