QuickBooks Online API Patterns

QuickBooks Online API Patterns

Overview

The QuickBooks Online (QBO) API is a RESTful JSON API that provides access to customers, invoices, payments, purchases, bills, vendors, accounts, items, estimates, credit memos, and financial reports. This skill covers OAuth2 authentication, the Intuit query language, pagination, error handling, and performance optimization patterns for MSP accounting workflows.

Authentication

OAuth2 Flow

QuickBooks Online uses OAuth2 for authentication. All API requests require a valid Bearer token in the Authorization header:

GET /v3/company/1234567890/customer/1
Authorization: Bearer eyJlbmMiOiJBMTI4Q0JDLUhT...
Accept: application/json
Content-Type: application/json

Required Headers:

| Header | Value | Description | |--------|-------|-------------| | Authorization | Bearer {access_token} | OAuth2 access token | | Accept | application/json | Response format | | Content-Type | application/json | Request body format |

Environment Variables

export QBO_CLIENT_ID="your-client-id"
export QBO_CLIENT_SECRET="your-client-secret"
export QBO_REALM_ID="your-company-id"
export QBO_ACCESS_TOKEN="your-access-token"
export QBO_REFRESH_TOKEN="your-refresh-token"
export QBO_ENVIRONMENT="production"  # or "sandbox"

Base URL Pattern

All API endpoints follow the pattern:

https://{base}/v3/company/{realmId}/{resource}

Production:

https://quickbooks.api.intuit.com/v3/company/1234567890/invoice

Sandbox:

https://sandbox-quickbooks.api.intuit.com/v3/company/1234567890/invoice

The realmId (Company ID) is a unique numeric identifier for each QuickBooks company. It is required in every API URL.

Minor Version Header

QuickBooks Online uses a minorversion query parameter to control API behavior. Always specify the latest minor version to access current features:

GET /v3/company/1234567890/customer/1?minorversion=73
Authorization: Bearer {access_token}

If omitted, the API defaults to the earliest supported minor version, which may lack newer fields or features.

Token Lifecycle

| Token | Lifetime | Refresh Method | |-------|----------|----------------| | Access Token | 60 minutes | Use refresh token | | Refresh Token | 100 days | Re-authorize if expired |

Token Refresh Flow

const OAuthClient = require('intuit-oauth');

const oauthClient = new OAuthClient({
  clientId: process.env.QBO_CLIENT_ID,
  clientSecret: process.env.QBO_CLIENT_SECRET,
  environment: process.env.QBO_ENVIRONMENT || 'production',
  redirectUri: 'http://localhost:3000/callback'
});

async function refreshAccessToken() {
  oauthClient.setToken({
    access_token: process.env.QBO_ACCESS_TOKEN,
    refresh_token: process.env.QBO_REFRESH_TOKEN,
    token_type: 'bearer'
  });

  const authResponse = await oauthClient.refresh();
  const newTokens = authResponse.getJson();

  // Store new tokens securely
  process.env.QBO_ACCESS_TOKEN = newTokens.access_token;
  process.env.QBO_REFRESH_TOKEN = newTokens.refresh_token;

  return newTokens;
}

Using node-quickbooks SDK

The node-quickbooks SDK (61k weekly downloads) simplifies authentication and API calls:

const QuickBooks = require('node-quickbooks');

const qbo = new QuickBooks(
  process.env.QBO_CLIENT_ID,
  process.env.QBO_CLIENT_SECRET,
  process.env.QBO_ACCESS_TOKEN,
  false, // no token secret (OAuth2)
  process.env.QBO_REALM_ID,
  process.env.QBO_ENVIRONMENT === 'sandbox',
  true,  // enable debug
  null,  // minor version (null = latest)
  '2.0', // OAuth version
  process.env.QBO_REFRESH_TOKEN
);

Intuit Query Language

QuickBooks Online uses a SQL-like query language for searching and filtering entities. Queries are sent via GET request to the /query endpoint.

Query Syntax

SELECT * FROM EntityName WHERE condition [AND condition] [ORDERBY field [ASC|DESC]] [STARTPOSITION n] [MAXRESULTS n]

Query Examples

Find customers by name:

GET /v3/company/{realmId}/query?query=SELECT * FROM Customer WHERE DisplayName LIKE '%Acme%'&minorversion=73

Find unpaid invoices for a customer:

GET /v3/company/{realmId}/query?query=SELECT * FROM Invoice WHERE CustomerRef = '123' AND Balance > '0'&minorversion=73

Find recent invoices:

GET /v3/company/{realmId}/query?query=SELECT * FROM Invoice WHERE TxnDate > '2026-01-01' ORDERBY TxnDate DESC&minorversion=73

Find active items:

GET /v3/company/{realmId}/query?query=SELECT * FROM Item WHERE Active = true&minorversion=73

Count customers:

GET /v3/company/{realmId}/query?query=SELECT COUNT(*) FROM Customer&minorversion=73

Query Operators

| Operator | Description | Example | |----------|-------------|---------| | = | Equals | CustomerRef = '123' | | != | Not equals | Balance != '0' | | < | Less than | Balance < '1000' | | > | Greater than | Balance > '0' | | <= | Less than or equal | TxnDate <= '2026-01-31' | | >= | Greater than or equal | TxnDate >= '2026-01-01' | | LIKE | Pattern match (% wildcard) | DisplayName LIKE '%Acme%' | | IN | Set membership | Id IN ('1', '2', '3') | | AND | Logical AND | Active = true AND Balance > '0' |

Query Pagination

Use STARTPOSITION and MAXRESULTS for pagination:

SELECT * FROM Customer STARTPOSITION 1 MAXRESULTS 100
SELECT * FROM Customer STARTPOSITION 101 MAXRESULTS 100
SELECT * FROM Customer STARTPOSITION 201 MAXRESULTS 100

Pagination Details:

| Parameter | Description | Default | Maximum | |-----------|-------------|---------|---------| | STARTPOSITION | 1-based offset | 1 | - | | MAXRESULTS | Results per page | 100 | 1000 |

Iterating All Results

async function queryAll(entityName, whereClause = '') {
  const allResults = [];
  let startPosition = 1;
  const maxResults = 1000;
  let hasMore = true;

  while (hasMore) {
    let query = `SELECT * FROM ${entityName}`;
    if (whereClause) query += ` WHERE ${whereClause}`;
    query += ` STARTPOSITION ${startPosition} MAXRESULTS ${maxResults}`;

    const response = await fetch(
      `${baseUrl}/v3/company/${realmId}/query?query=${encodeURIComponent(query)}&minorversion=73`,
      { headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' } }
    );

    const data = await response.json();
    const entities = data.QueryResponse[entityName] || [];
    allResults.push(...entities);

    hasMore = entities.length === maxResults;
    startPosition += maxResults;
  }

  return allResults;
}

Request Format

Standard JSON Request

QuickBooks Online uses standard JSON for request and response bodies:

{
  "DisplayName": "Acme Corporation",
  "PrimaryPhone": {
    "FreeFormNumber": "555-123-4567"
  },
  "PrimaryEmailAddr": {
    "Address": "billing@acmecorp.com"
  }
}

Response Format

Single Resource (Read/Create/Update):

{
  "Customer": {
    "Id": "123",
    "DisplayName": "Acme Corporation",
    "Balance": 5000.00,
    "SyncToken": "2",
    "MetaData": {
      "CreateTime": "2025-06-15T10:30:00-07:00",
      "LastUpdatedTime": "2026-01-20T14:22:00-07:00"
    }
  },
  "time": "2026-02-23T10:00:00.000-07:00"
}

Query Response (Collection):

{
  "QueryResponse": {
    "Customer": [
      { "Id": "1", "DisplayName": "Acme Corporation", "Balance": 5000.00 },
      { "Id": "2", "DisplayName": "TechStart Inc", "Balance": 1200.00 }
    ],
    "startPosition": 1,
    "maxResults": 2,
    "totalCount": 2
  },
  "time": "2026-02-23T10:00:00.000-07:00"
}

SyncToken (Optimistic Locking)

Every entity has a SyncToken field that must be included in update requests. This prevents concurrent modification conflicts:

{
  "Id": "123",
  "SyncToken": "2",
  "DisplayName": "Acme Corporation - Updated"
}

If the SyncToken does not match the current value on the server, the update