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.

Key Considerations

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.

Unsupported Endpoints

Not all QuickBooks types support pagination. This is a limitation of QuickBooks Desktop. For endpoints that do not support pagination the max limit will be set to 500 items by default.

Examples

SDK Auto-Pagination

import { NxusClient } from '@nxus/sdk';

const client = new NxusClient({
  apiKey: process.env.NXUS_API_KEY,
  headers: {
    'X-Connection-ID': 'YOUR_CONNECTION_ID',
  },
});

// ── Page-by-page iteration ──
let cursor: string | undefined;

do {
  const result: Page<Invoice> = await nxus.invoices.list({
    connectionId: 'conn_abc123',
    limit: 10,
    cursor,
  });

  for (const invoice of result.data) {
    console.log(invoice);
  }

  cursor = result.nextCursor ?? undefined;
} while (cursor);

Manual Page Control

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

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
}