You can filter collections using the filter query parameter, which supports standard comparison operators such as =, >=, and !=. You can specify multiple filter parameters by joining filter statements with an ampersand (&).

To determine the parameters that can be filtered for a given method, see the API Reference. The filterable fields are also returned with the request in the X-Clover-Allowed-Filter-Fields header.

Example 1—Request filtered by clientCreatedTime

This request retrieves orders for a specific merchant within a given time range, defined by the clientCreatedTime field.

curl
-s "https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders?filter=clientCreatedTime>=[unix-time]&filter=clientCreatedTime<=[unix-time]" 
--header "Authorization: Bearer {API_Token}"

Example 2—Request filtered by total and payType

This request is to retrieve orders that meet specific criteria, such as having a total amount greater than 1000 and a payment type other than "FULL." This can help analyze high-value transactions and understand different payment methods used.

curl
-s "https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders?filter=total>1000&filter=payType!=FULL"
--header "Authorization: Bearer {API_Token}"

{
    "elements": [
        {
            "clientCreatedTime": 1401286267000,
            "createdTime": 1401286268000,
            "currency": "USD",
            "employee": {
                "id": "QT0DES4CXR572"
            },
            "groupLineItems": true,
            "href": "https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/8WAD6KV8D90KR",
            "id": "8WAD6KV8D90KR",
            "isVat": false,
            "manualTransaction": false,
            "modifiedTime": 1401286463000,
            "payType": "SPLIT_CUSTOM",
            "state": "locked",
            "taxRemoved": false,
            "testMode": false,
            "total": 5293
        },
        {
            "clientCreatedTime": 1400106245000,
            "createdTime": 1400106245000,
            "currency": "USD",
            "employee": {
                "id": "QT0DES4CXR572"
            },
            "groupLineItems": true,
            "href": "https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/0S0JJYG231462",
            "id": "0S0JJYG231462",
            "isVat": false,
            "manualTransaction": false,
            "modifiedTime": 1400106366000,
            "payType": "SPLIT_CUSTOM",
            "state": "locked",
            "taxRemoved": false,
            "testMode": false,
            "total": 2829
        }
    ],
    "href": "https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders?filter=total%3E1000&filter=payType!%3DFULL&limit=100"
}

Example 3—Filtering by date and handling the 90-day restriction

When querying for historical data using time-based filters, it is important to understand a key limitation on certain Clover API endpoints. Endpoints like getOrders, getPayments, and getRefunds will only return data spanning a maximum of 90 days in a single request.

This section explains the 90-day restriction, shows how to formulate the necessary date-based filters, and provides the required strategy for retrieving a complete historical data set that goes beyond a 90-day window.

Understanding the 90-day data restriction

IMPORTANT: Time-based filters are restricted to a 90-day range.

When you use a time-based filter in a request (for example, createdTime, clientCreatedTime, or modifiedTime), the server returns a maximum of 90 days of data. If your request spans a period longer than 90 days, the server automatically adjusts the time frame to return only the most recent 90 days of data from that range.

Because of this restriction, you must "paginate" through your data manually by adjusting the time filter in 90-day increments.

Formulating Date-Filter Queries

The following examples show how to use query operators when making single-date and date-range requests.