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.

IMPORTANT: Time-based filters for some endpoints, such as getPayments and getRefunds, are restricted to a 90-day range.

When you use a time-based filter, for example, createdTime or clientCreatedTime, 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.

This affects your queries in the following ways:

• A request for six months of data returns only the last 90 days of that period.
• To retrieve a complete historical record, you must make multiple, sequential requests in 90-day increments.

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's 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 this 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 this 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.

Date-filter scenarios

The following examples show how to use query operators when making single-date and date-range requests. The example results table shows how the 90-day limit impacts the respective search results.

Operators used these examples:

• AND
• > ...(greater than)
• >= ...(greater than or equal to)
• < ...(less than)
• <= ...(less than or equal to)

Single-date requests

Single-date queries only specify the beginning or the end date, for example:

• >{date1} ...(get all payments after {date1})
• >={date1} ...(get all payments after or on {date1})
• <{date1} ...(get all payments before {date1})
• <={date1} ...(get all payments before or on {date1})

Date-range requests

Date-range queries specify the beginning and end of a date range, for example:

• >{date1} AND <{date2} ...(get all payments after {date1} and before {date2})
• >{date1} AND <={date2} ...(get all payments after {date1} and before or on {date2})
• <={date1} AND <{date2} ...(get all payments after or on {date1} and before {date2})
• <={date1} AND <={date2} ...(get all payments after or on {date1} and before or on {date2})

Example query results

To illustrate the impact of the 90-day limit applied to query results, this table shows sample results expected with and without the 90-day limit for simple single-date requests. For date-range requests, the results can be extrapolated. In these examples, {date1} is Jan 1, 2024.