• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Search orders

POST /v2/orders/search

Search all orders for one or more locations.

Orders include all sales, returns, and exchanges regardless of how or when they entered the Square ecosystem (such as Point of Sale, Invoices, and Connect APIs).

SearchOrders requests need to specify which locations to search and define a SearchOrdersQuery object that controls how to sort or filter the results. Your SearchOrdersQuery can:

Set filter criteria. Set the sort order. Determine whether to return results as complete Order objects or as OrderEntry objects.

Note that details for orders processed with Square Point of Sale while in offline mode might not be transmitted to Square for up to 72 hours. Offline orders have a created_at value that reflects the time the order was created, not the time it was subsequently transmitted to Square.

Permissions
ORDERS_READ
Guide
Search orders Try in API Explorer

Request Body

Example code
Name Description
location_ids
string [ ]

The location IDs for the orders to query. All locations must belong to the same merchant.

Min: 1 location ID.

Max: 10 location IDs.
cursor
string

A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination.
query
SearchOrdersQuery

Query conditions used to filter or sort the results. Note that when retrieving additional pages using a cursor, you must use the original query.
limit
integer (32-bit)

The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page.

Default: 500

Min 1
return_entries
boolean

A Boolean that controls the format of the search results. If true, SearchOrders returns OrderEntry objects. If false, SearchOrders returns complete order objects.

Default: false.

Response Fields
Name Description
order_entries
OrderEntry [ ]

A list of OrderEntries that fit the query conditions. The list is populated only if return_entries is set to true in the request.
orders
Order [ ]

A list of Order objects that match the query conditions. The list is populated only if return_entries is set to false in the request.
cursor
string

The pagination cursor to be used in a subsequent request. If unset, this is the final response. For more information, see Pagination.
errors
Error [ ]

Errors encountered during the search.

Examples

You are viewing an old version of the API
POST /v2/orders/search
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/orders/search \
  -X POST \
  -H 'Square-Version: 2022-07-20' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "return_entries": true,
    "limit": 3,
    "location_ids": [
      "057P5VYJ4A5X1",
      "18YC4JDH91E1H"
    ],
    "query": {
      "filter": {
        "date_time_filter": {
          "closed_at": {
            "start_at": "2018-03-03T20:00:00+00:00",
            "end_at": "2019-03-04T21:54:45+00:00"
          }
        },
        "state_filter": {
          "states": [
            "COMPLETED"
          ]
        }
      },
      "sort": {
        "sort_field": "CLOSED_AT",
        "sort_order": "DESC"
      }
    }
  }'
Response JSON 
{
  "order_entries": [
    {
      "order_id": "CAISEM82RcpmcFBM0TfOyiHV3es",
      "location_id": "057P5VYJ4A5X1",
      "version": 1
    },
    {
      "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY",
      "location_id": "18YC4JDH91E1H"
    },
    {
      "order_id": "CAISEM52YcpmcWAzERDOyiWS3ty",
      "location_id": "057P5VYJ4A5X1"
    }
  ],
  "cursor": "123"
}