Pagination

Conductor’s QuickBooks Desktop API v2.0 uses cursor-based pagination to handle large datasets efficiently, allowing you to retrieve results in manageable chunks. This guide explains how to implement pagination and its key limitations.

​

How pagination works

For list endpoints that support pagination (indicated by the presence of a cursor query parameter in the API specification), the process works as follows:

1. Make your initial request to the list endpoint without a cursor.

   • Use the limit query parameter to control how many items are returned per page.
     • The default and maximum value is 150 items per page. We enforce this limit to prevent overloading QuickBooks Desktop.

2. The response will contain the following pagination fields:

   • nextCursor - The cursor value to use when requesting the next page of results. This field is null if there are no more pages.
   • hasMore - Indicates whether there are more pages of results available.
   • remainingCount - The number of remaining items that can be retrieved in subsequent pages.

3. To fetch the next page, make another request with the cursor query parameter set to the nextCursor value from the previous response.

   • You must make subsequent pagination requests within 10 seconds of receiving the previous response. If you exceed this time limit, you’ll receive an error.
   • This limitation is inherent to QuickBooks Desktop’s design.
   • While this is not an issue when using code to automatically fetch pages in sequence (e.g., in a loop), it may affect manual API testing where you’re copying and pasting cursor values between requests.

4. Repeat until hasMore is false.

5. Attempting to request another page when hasMore is false will result in an error.

​

Important limitations

​

Same cursor value used for all pages

The cursor value remains constant throughout the entire pagination sequence. This means you should reuse the same cursor value for all subsequent requests in the sequence, which is a design characteristic inherent to the QuickBooks Desktop system.

​

No custom sorting available

The order of results is determined entirely by QuickBooks Desktop, and no information about the ordering is provided in the response. Due to this limitation, custom sorting of results is not supported through the API.

​

Non-paginated endpoints

Some QuickBooks Desktop list APIs do not support pagination due to limitations in QuickBooks Desktop itself. These endpoints can be identified by the absence of the cursor parameter in their API specification. This typically applies to endpoints where the end-user is highly unlikely to have a large set of objects of that type, so the absence of pagination will not impact performance.

​

Pagination in Conductor SDKs

Our official client libraries handle pagination automatically, making it easier to work with paginated responses. Check out their documentation for implementation details:

• Node.js SDK
• Python SDK

​

Example

1. Initial request:

   GET https://api.conductor.is/v1/quickbooks_desktop/customers
   

   Example initial response

   {
     "data": [...],
     "nextCursor": "abc123",
     "hasMore": true,
     "remainingCount": 99
   }
   

2. Next page request with cursor query parameter:

   GET https://api.conductor.is/v1/quickbooks_desktop/customers?cursor=abc123
   

   Example next page response

   {
     "data": [...],
     "nextCursor": "abc123",
     "hasMore": false,
     "remainingCount": 0
   }
   

3. Requesting another page after hasMore is false will result in an error:

   GET https://api.conductor.is/v1/quickbooks_desktop/customers?cursor=abc123
   

   Example error response

   {
     "error": {
       "message": "No more results available"
       // ...
     }
   }