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 the our current baseURLs </app/developer/qbo/docs/get-started/create-a-request>_.

These are the common HTTP header fields for requests.

See an 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.

See an 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:

2015-07-24T10:33:39-07:00

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

• If your app is accessing endpoints other than QuickBooks Online API endpoints, there is a combined limit of 800 requests per minute, per realm ID and app. Meaning, our servers will throttle requests after an app sends 500 requests per min across all the realms (i.e. company file) combined, or 500 requests for a single realm - whichever condition is satisfied first.
• 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 1,000. To handle more than 1000, use pagination to fetch the entities in chunks.

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.