Basic schema and data formats for the QuickBooks Online Accounting API

The QuickBooks Online Accounting API is based on the REST framework. Here’s a quick guide for relevant REST features, operations, formats, and attributes.

• What is REST?
• Common REST naming conventions

See our current baseURLs.

These are the common HTTP header fields for requests.

Example POST request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

POST /v3/company/12345678/invoice HTTP/1.1
Host: quickbooks.api.intuit.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJlbmMiOiJ**************xPfzFFw
Host: quickbooks.api.intuit.com

{
   "Line": [
      {
         "Amount": 100.00,
         "DetailType": "SalesItemLineDetail",
         "SalesItemLineDetail": {
            "ItemRef": {
               "value": "1",
               "name": "Services"
            }
         }
      }
   ],
   "CustomerRef": {
      "value": "1"
   }
}

These are common HTTP header fields for responses from our servers.

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
Date: Thu, 07 Jan 2016 17:19:22 GMT
Expires: 0
intuit_tid: gw-756b01cf-3fe0-4414-a2a2-321dd2287b7b
Keep-Alive: timeout=5
QBO-Version: 1512.462
Server: nginx/1.8.0
Strict-Transport-Security: max-age=15552000
Transfer-Encoding: chunked
Vary: Accept-Encoding
Via: 1.1 ipp-gateway-ap05

{
 "Invoice": {
...

 },
 "time": "2016-01-07T09:19:21.923-08:00"
}

Here are detailed definitions of common IDs and data fields used throughout our API.

Any value supplied in a read-only attribute is transient and will be silently overwritten by QuickBooks data services. No error is returned. Learn more about updating read-only attributes.

US versions of QuickBooks Online support ISO-8859-1 (extended ASCII) character encoding.

Non-US versions of QuickBooks Online support UTF-8 character encoding.

The basic format is: <date>T<time><UTC offset>

Timestamps returned in QuickBooks Online Accounting API response payloads and webhooks notifications are in DateTime format. This conforms to the iCal date/time format, as defined in RFC 2445.

Here’s an example timestamp:

2025-02-24T10:33:39-07:00

This represents 03:33:39 on 24 February 2025, in a time zone west of UTC by 07:00 hours.

• If your app accesses endpoints other than QuickBooks Online, there is a combined limit of 800 requests per minute, per realm ID and app.
• You’ll see HTTP Status Code 429 when throttling occurs. If you see this, wait 60 seconds before retrying the request.
• Any requests that take longer than 120 seconds to execute will time out. Keep this in mind when determining how many payloads to include in a single batch request.
• The maximum number of entities returned in a query response is 1000. To handle more than 1000, use pagination to fetch the entities in chunks.
• Each transaction (except Journal Entry) can contain a maximum of 10,000 line items.
• Each transaction (except Journal Entry) can be linked to a maximum of 10,000 transactions (includes transaction-level and line-level links).
• Each transaction (except Journal Entry) can contain a maximum of 10,000 attachments.

The current version of the QuickBooks Online Accounting API supports minor versions.

This lets you access incremental changes and continue using specific versions of API entities so you don’t break existing apps. Here’s how to access minor versions.