QuickBooks Online API caps query results at 100 rows by default

When scripts that query QuickBooks Online for customer records stop processing after exactly 100 entries, the cause is a built-in pagination limit in the QuickBooks API — not a bug in the integration code. The API returns a maximum of 100 rows per query by default, regardless of how many records actually exist in the company file.

The symptom

A developer attempting to iterate through roughly 1,800 QuickBooks Online customer records — to prepend each customer’s display name with an internally assigned company ID — found that the script consistently processed only the first 100 customers and then stopped. Each run of the script behaved identically, handling precisely 100 records before exiting without error. The query itself executed successfully, and the customers it did return were valid and correctly formatted, which made the truncation easy to overlook as a data problem rather than a pagination issue.

Why it happens

QuickBooks Online enforces a server-side cap on the number of records returned in a single query response. The default ceiling is 100 rows. This behavior is by design and applies across query operations — customer queries, invoice queries, and other record types all operate under the same constraint. The limit exists to keep response payloads manageable and to prevent individual API calls from placing excessive load on the QuickBooks servers.

The important detail is that the API does not signal the truncation as an error. The response looks complete, contains valid data, and returns without throwing an exception. A script that simply loops through the result set and exits will silently process only the first batch, leaving the remaining records untouched. For anyone working with a QuickBooks Online company file that contains hundreds or thousands of records, this means a single query call will never retrieve the full set on its own.

The accepted fix

The solution is to implement pagination using two query parameters that the QuickBooks API exposes for precisely this purpose. The first parameter controls the starting position — the offset within the full result set where the returned batch begins. The second parameter controls the maximum number of records returned in that batch.

By incrementing the starting position in steps and issuing repeated query calls, a script can walk through the entire result set in sequential pages of up to 100 records each. A typical approach sets the maximum results value to 100, begins the first query at position 1, and then advances the starting position by 100 on each subsequent call until a query returns fewer than 100 records — signaling that the final page has been reached.

For a customer list of 1,800 records, this means the script would issue roughly 18 paginated queries rather than a single call. Each page is processed in turn, and the update operation runs against every customer in the file rather than just the first hundred.

Practical considerations

A few details are worth keeping in mind when building pagination into a QuickBooks Online integration. First, the maximum results value can be set below 100 if smaller batches are preferable, but it cannot be used to bypass the 100-row ceiling in a single call. Second, because each page requires a separate round-trip to the QuickBooks servers, scripts processing large record sets will take longer than a single-query approach — a trade-off that is unavoidable given the API’s design. Third, if records are being modified during the pagination run, the result set can shift between pages, so it is generally best to run bulk-update operations during a window when other users are not actively adding or editing the same record type.

For developers maintaining custom QuickBooks Online integrations that depend on complete record retrieval, building pagination in from the start avoids the silent truncation that catches many first-time integrators off guard.