You are viewing an old version of the API

All Versions

Search orders

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 (e.g. Point of Sale, Invoices, Connect APIs, etc).

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

Set filter criteria. Set 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 may 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.

Required permissions: ORDERS_READ

Open in API Explorer

Request Body

Name	Description
`location_ids string [ ]`	The location IDs for the orders to query. All locations must belong to the same merchant. Min: 1 location IDs. Max: 10 location IDs.
`cursor string`	A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See Pagination for more information.
`query SearchOrdersQuery`	Query conditions used to filter or sort the results. Note that when fetching additional pages using a cursor, the query must be equal to the query used to fetch the first page of results.
`limit integer`	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`	Boolean that controls the format of the search results. If `true`, SearchOrders will return `OrderEntry` objects. If `false`, SearchOrders will return complete Order objects. Default: `false`.

Response Fields

Name	Description
`order_entries OrderEntry [ ]`	List of OrderEntries that fit the query conditions. Populated only if `return_entries` was set to `true` in the request.
`orders Order [ ]`	List of Order objects that match query conditions. Populated only if `return_entries` in the request is set to `false`.
`cursor string`	The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Pagination for more information.
`errors Error [ ]`	Errors encountered during the search.

Examples

All Versions

curl https://connect.squareup.com/v2/orders/search \
  -X POST \
  -H 'Square-Version: 2020-06-25' \
  -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"
      }
    }
  }'

{
  "order_entries": [
    {
      "order_id": "CAISEM82RcpmcFBM0TfOyiHV3es",
      "location_id": "057P5VYJ4A5X1",
      "version": 1
    },
    {
      "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY",
      "location_id": "18YC4JDH91E1H"
    },
    {
      "order_id": "CAISEM52YcpmcWAzERDOyiWS3ty",
      "location_id": "057P5VYJ4A5X1"
    }
  ],
  "cursor": "123"
}

Orders API You are viewing an old version of the API 2020-06-25 Version 2020-06-25 All Versions Orders API Search orders

Request Body

Response Fields

Examples

Share Feedback

You are viewing an old version of the API

All Versions

Search orders