Pagination

nXus uses cursor-based pagination to deliver large datasets from QuickBooks Desktop in manageable, high-performance increments.

The Pagination Workflow

1. Initial Call: Request a resource (e.g., GET /Customers) with an optional limit (max 150).
2. Token Retrieval: Capture the nextCursor from the response JSON.
3. Continuous Fetching: Call the same endpoint again, providing the cursor parameter. Repeat until hasMore is false.
4. Retry Logic: Cursor-based pagination continuation requests are not automatically retried. If a continuation request fails, restart the list operation from the beginning.

Note on Retries: QuickBooks Desktop cursors are stateful. If a network timeout occurs while fetching page 3, the cursor may become invalidated or expire. Do not retry the page 3 request; instead, discard the cursor and request page 1 again.

Sample Response Body

{
  "success": true,
  "requestId": "qibGUQ6cW5IJw09a5zEbJw",
  "data": [
    {
      "id": "100001-1039043346",
      "name": "Automobile Insurance Company",
      "balance": 3200,
      "isActive": true
    }
  ],
  "nextCursor": "hUz-6rRtSsW9Zo4H-0QO9Q",
  "page": 1,
  "count": 1,
  "limit": 10,
  "totalCount": 60,
  "hasMore": true,
  "remainingCount": 59
}

SDK Auto-Pagination (The Recommended Path)

import { NxusClient } from 'nxus-qbd';

const client = new NxusClient({
  apiKey: process.env.NXUS_API_KEY,
});

// ── Auto-pagination ──
for await (const invoice of client.invoices.list({
  connectionId: 'conn_abc123',
  limit: 10,
})) {
  console.log(invoice);
}

Raw REST (cURL) Example

When making raw HTTP requests, pass the nextCursor from your initial response as the cursor query parameter in subsequent calls.

curl -X GET "[https://api.nx-us.net/api/v1/Customers?cursor=hUz-6rRtSsW9Zo4H-0QO9Q](https://api.nx-us.net/api/v1/Customers?cursor=hUz-6rRtSsW9Zo4H-0QO9Q)" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-connection-id: conn_abc123"

Early Close — Find-and-Stop Pattern

When you break out of an SDK auto-pagination loop early, the SDK automatically calls POST /api/v1/cursors/{cursor}/close behind the scenes. This releases the QuickBooks Desktop connection lane in milliseconds rather than waiting for the 10-second silent-client timeout.

Find-and-stop example

A common pattern is paginating until you find a specific record, then stopping:

import { NxusClient } from 'nxus-qbd';

const nxus = new NxusClient({ apiKey: process.env.NXUS_API_KEY });

let target;

for await (const customer of nxus.customers.list({
  connectionId: 'conn_abc123',
  limit: 50,
})) {
      if (customer.name === 'Acme Corp') {
        target = customer;
        break; // SDK auto-closes the cursor here
      }
}

if (target) {
  console.log(`Found: ${target.name} (balance: ${target.balance})`);
}

Cursor Close Endpoint

Explicitly closes a pagination cursor to release the QuickBooks Desktop connection lane immediately. This endpoint is signal-only and idempotent — it always returns 204 No Content, even if the cursor has already expired or doesn’t exist. No information is leaked about other tenants’ cursors.

SDK users never need to call this directly. It fires automatically when you break out of an auto-pagination loop.

Limitations & Edge Cases

Static Cursors

Unlike some APIs where the cursor changes every page, the nXus cursor stays constant for the duration of your fetch sequence.

Sorting

Data is returned according to QuickBooks Desktop’s internal indexing. Custom sort fields are not supported in paginated requests.

Manual Page Control

Await the first page when you need to inspect each page boundary, then keep calling getNextPage() until hasNextPage() returns false.

import { NxusClient } from 'nxus-qbd';

const client = new NxusClient({
  apiKey: process.env.NXUS_API_KEY,
});

// Fetch the first page manually
let page = await client.invoices.list({
  connectionId: 'conn_abc123',
  limit: 50,
});

console.log(`Fetched ${page.data.length} items.`);

// Manually paginate using the page object
while (page.hasNextPage()) {
  page = await page.getNextPage();
  console.log(`Fetched ${page.data.length} more items.`);
}

Non-Paginated List Endpoints

Not all QuickBooks types support pagination. This is a limitation of the underlying QuickBooks Desktop architecture.

For the endpoints listed below, you will still use the standard GET list pattern to retrieve multiple records (e.g., GET /api/v1/Accounts). However, the API will return a flat array of up to 500 items by default, rather than the standard pagination envelope.

Sample Response Body

{
  "success": true,
  "requestId": "qibGUQ6cW5IJw09a5zEbJw",
  "data": [
    {
      "id": "80000001-123456789",
      "name": "Checking Account",
      "balance": 15000.00
    },
    {
      "id": "80000002-123456789",
      "name": "Savings Account",
      "balance": 5000.00
    }
  ]
}

Unsupported Endpoints

Flat Response Shape

Because these endpoints cannot be paginated, the response will not include nextCursor, hasMore, or page counts.

SDK Behavior

If you attempt to use the .list() (or equivalent streaming) methods on these specific endpoints, the SDK will simply return the single array of data and complete the loop immediately.