How to Integrate QuickBooks API

The QuickBooks API Integration Uses a SQL-Like Query Language Instead of Standard REST Endpoints

Most APIs let you call a resource URL with filters: /invoices?customer_id=123. QuickBooks works differently.

You send a SELECT statement to a single query endpoint
SELECT * FROM Invoice WHERE CustomerRef = '123' STARTPOSITION 1 MAXRESULTS 100


This query goes to /v3/company/{realmId}/query as a URL-encoded string. Instead of passing filters as query parameters, you construct an entire SQL-like statement with WHERE clauses, operators, and pagination keywords baked into the syntax. The WHERE clause supports AND but not OR. Operators include =, <, >, <=, >=, IN, and LIKE with % wildcard only. The ID field is more restrictive and only accepts = and IN.

For teams building generic API clients or shared integration layers, this creates real friction. Standard REST client libraries, SDK abstractions, and API gateway patterns do not accommodate SQL-like query construction out of the box. Your integration layer needs a dedicated query builder that constructs valid QuickBooks SELECT statements, encodes them correctly, and handles the quirks of a query language that looks like SQL but is not.

Maesn Normalizes the QuickBooks Query Language: Standard REST Endpoints Replace SQL-Like Syntax

With Maesn, the SQL syntax is completely abstracted. Engineers call standard REST endpoints with familiar parameters. Maesn translates these into QuickBooks SELECT statements internally.

The QuickBooks API Integration Paginates with STARTPOSITION Instead of Standard Page Parameters

QuickBooks has no page/per_page parameters, no Link headers, and no cursors. Pagination uses STARTPOSITION and MAXRESULTS inside the query syntax:

SELECT * FROM Customer STARTPOSITION 1 MAXRESULTS 100
SELECT * FROM Customer STARTPOSITION 101 MAXRESULTS 100
SELECT COUNT(*) FROM Customer


The maximum is 1,000 records per response, and the default is 100. To know how many total records exist, you need to run a separate COUNT(*) query, which returns only a totalCount value and no actual data. There is no "next page" indicator in the response. Your sync logic must manually increment the STARTPOSITION value after each query, track where it left off, and handle the case where records are added or deleted between requests.

This offset-based approach also means your integration cannot display sync progress or estimate completion time without first making the extra COUNT call. For large datasets with thousands of records, paging through everything requires multiple sequential requests with no way to guarantee consistency across them.

Maesn Manages QuickBooks Pagination Entirely: Page-Based Responses with Total Counts Included

Maesn handles offset tracking and COUNT queries internally. Your product receives standard page-based responses with total counts included, independent of how QuickBooks paginates natively.

The QuickBooks API Integration Enforces Multi-Layer Rate Limiting

The QuickBooks API limits requests at multiple levels simultaneously. There is no single number to stay below. Your integration must respect all of the following at the same time:

500 requests/minute per company (realm ID)
10 requests/second per company and app
40 batch requests/minute per company and app

HTTP 429 → wait 60 seconds

Monthly cap: 500,000 API calls (Builder tier)


When any of these limits is exceeded, the API returns HTTP 429. The recommended wait time is 60 seconds. Requests that take longer than 120 seconds will time out entirely. For SaaS products that connect many QuickBooks companies, the per-company limits apply independently to each connected company, but the monthly cap applies at the app level across all connections.

This multi-layer structure makes rate limit management significantly harder than a single-bucket approach. Your integration must track per-second, per-minute, batch, and monthly usage at the same time, and implement backoff logic that respects each layer independently. A request that passes the per-second check can still fail on the per-minute limit, which adds complexity to any retry strategy.

Maesn Handles QuickBooks Rate Limits Automatically: All Throttling Layers Are Managed Internally

Maesn tracks and respects all rate limit layers for QuickBooks. If a request is throttled, retry logic with appropriate backoff runs automatically. The Maesn Dashboard provides real-time observability into API usage and errors.

The QuickBooks API Integration Requires OAuth 2.0 with Short-Lived Tokens

QuickBooks requires OAuth 2.0 for all external applications. Access tokens expire after 60 minutes (3,600 seconds). Refresh tokens have a rolling expiry of 100 days. If a refresh token expires without being used, the customer must complete a full re-authorization flow from scratch.

Access token:  60 minutes
Refresh token: 100 days (rolling)
Scope:         com.intuit.quickbooks.accounting

Token endpoint:
 POST https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer


The 60-minute access token window is short. For integrations that run long sync jobs, batch operations, or background processing, the token will expire mid-operation. Your integration must detect token expiration, refresh the token using the refresh endpoint, retry the failed request, and do all of this without disrupting the user experience or losing progress on the current operation.

The 100-day rolling refresh token adds another failure mode. If a customer stops using your integration for more than 100 days, the refresh token expires silently. The next API call fails, and the only recovery path is asking the customer to re-authorize your app. This creates support tickets, confusion, and churn risk for connections that were technically working before the inactivity window.

Maesn Manages QuickBooks Authentication Entirely: Token Refresh and Re-Authorization Are Handled Centrally

Maesn refreshes tokens automatically before expiration and detects when re-authorization is needed. Engineers do not build token lifecycle logic. Authentication is handled at the platform level.

QuickBooks Partner Program and Marketplace Listing

QuickBooks offers a structured partner program through the Intuit Developer Portal. A free developer sandbox is available for building and testing your integration. Production access requires registering at the developer portal and creating your app. The program is free to start, with a cap of 500,000 API calls per month under the initial Builder tier.

For marketplace visibility, QuickBooks requires at least Silver partner status to list in the QuickBooks App Store. The App Store is a significant growth channel with strong co-marketing programs available to qualified partners.

Maesn Supports the QuickBooks Partner Listing Process

Unlike most unified API providers, Maesn does not put its name on your marketplace listing. The app in the QuickBooks App Store carries your name and logo. Your brand appears during authentication, and you can pursue co-marketing activities directly with Intuit. Maesn handles the technical complexity so you can focus on the growth side. For a full breakdown of partnership requirements across all supported systems, read the Maesn accounting integration partnerships guide.

Why Teams Use Maesn for Their QuickBooks API Integration

Integrating directly with the QuickBooks API means building a SQL-like query builder, managing manual pagination offsets, tracking four layers of rate limits, and refreshing OAuth tokens every 60 minutes. Each of these is solvable on its own, but together they create a maintenance surface that grows with every connected customer.

Maesn abstracts all of it behind a unified API. One integration gives you standard REST endpoints, consistent pagination, managed authentication, rate limit handling, and access to 30+ additional accounting systems including DATEV, Exact Online, Xero, Moneybird, and more.

‍

Check the Maesn documentation for QuickBooks or talk to the Maesn team to get started.