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.

Servers

https://connect.squareup.com

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name	Type	Required	Description
`query`	Object	No	Contains query criteria for the search.
`query.filter`	Object	No	Filtering criteria to use for a `SearchOrders` request. Multiple filters are ANDed together.
`query.filter.date_time_filter`	Object	No	Filter for `Order` objects based on whether their `CREATED_AT`, `CLOSED_AT`, or `UPDATED_AT` timestamps fall within a specified time range. You can specify the time range and which timestamp to filter for. You can filter for only one time range at a time. For each time range, the start time and end time are inclusive. If the end time is absent, it defaults to the time of the first request for the cursor. Important: If you use the `DateTimeFilter` in a `SearchOrders` query, you must set the `sort_field` in OrdersSort to the same field you filter for. For example, if you set the `CLOSED_AT` field in `DateTimeFilter`, you must set the `sort_field` in `SearchOrdersSort` to `CLOSED_AT`. Otherwise, `SearchOrders` throws an error. Learn more about filtering orders by time range.
`query.filter.date_time_filter.created_at`	Object	No	Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
`query.filter.date_time_filter.created_at.start_at`	String	No	A datetime value in RFC 3339 format indicating when the time range starts.
`query.filter.date_time_filter.created_at.end_at`	String	No	A datetime value in RFC 3339 format indicating when the time range ends.
`query.filter.date_time_filter.closed_at`	Object	No	Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
`query.filter.date_time_filter.closed_at.start_at`	String	No	A datetime value in RFC 3339 format indicating when the time range starts.
`query.filter.date_time_filter.closed_at.end_at`	String	No	A datetime value in RFC 3339 format indicating when the time range ends.
`query.filter.date_time_filter.updated_at`	Object	No	Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
`query.filter.date_time_filter.updated_at.start_at`	String	No	A datetime value in RFC 3339 format indicating when the time range starts.
`query.filter.date_time_filter.updated_at.end_at`	String	No	A datetime value in RFC 3339 format indicating when the time range ends.
`query.filter.customer_filter`	Object	No	A filter based on the order `customer_id` and any tender `customer_id` associated with the order. It does not filter based on the FulfillmentRecipient `customer_id`.
`query.filter.customer_filter.customer_ids[]`	Array	No	A list of customer IDs to filter by. Max: 10 customer IDs.
`query.filter.source_filter`	Object	No	A filter based on order `source` information.
`query.filter.source_filter.source_names[]`	Array	No	Filters by the Source `name`. The filter returns any orders with a `source.name` that matches any of the listed source names. Max: 10 source names.
`query.filter.fulfillment_filter`	Object	No	Filter based on order fulfillment information.
`query.filter.fulfillment_filter.fulfillment_states[]`	Array	No	A list of fulfillment states to filter for. The list returns orders if any of its fulfillments match any of the fulfillment states listed in this field.
`query.filter.fulfillment_filter.fulfillment_types[]`	Array	No	A list of fulfillment types to filter for. The list returns orders if any of its fulfillments match any of the fulfillment types listed in this field.
`query.filter.state_filter`	Object	No	Filter by the current order `state`.
`query.filter.state_filter.states[]`	Array	Yes	States to filter for.
`query.sort`	Object	No	Sorting criteria for a `SearchOrders` request. Results can only be sorted by a timestamp field.
`query.sort.sort_order`	String	No	The chronological order in which results are returned. Defaults to `DESC`.
`query.sort.sort_field`	String	Yes	The field to sort by. Important: When using a DateTimeFilter, `sort_field` must match the timestamp field that the `DateTimeFilter` uses to filter. For example, if you set your `sort_field` to `CLOSED_AT` and you use a `DateTimeFilter`, your `DateTimeFilter` must filter for orders by their `CLOSED_AT` date. If this field does not match the timestamp field in `DateTimeFilter`, `SearchOrders` returns an error. Default: `CREATED_AT`.
`limit`	Integer	No	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`
`location_ids[]`	Array	No	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	No	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.
`return_entries`	Boolean	No	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`.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.