Learn basic REST API features

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

General REST API info
Base URLs for the QuickBooks Payments API
Working environment URL
For sandbox company and testing (development) https://sandbox.api.intuit.com
For production apps https://api.intuit.com
Tip: Swap one of these base URLs with baseURL placeholder when you see them in sample queries or examples in our documentation.
URI formats for operations
Operation URI
Create and update POST baseURL/quickbooks/v4/resourceName
Read (single-entity) GET baseURL/quickbooks/v4/resourceName
Read (multi-entity) GET baseURL/quickbooks/v4/resourceName
Delete DELETE baseURL/quickbooks/v4/resourceName

URI component definitions

Component Description
baseURL Initial path to the URI. The Base URL section contains the list of available paths.
resourceName The name of the API entity you’re performing the operation for (i.e a bankaccount, charge, card, etc)
entityID The ID identifying the specific instance of the API entity.
Common request header fields

These are common HTTP header fields for requests.

Field name Description Required
Authorization Authentication credentials for HTTP authentication. Required for all requests. This represents the user’s permission to share access to their company data with your app. Learn more how to implement OAuth 2.0 and create this value. Required
Content-Length Length of the message (without the headers) according to RFC 2616. Required for POST operations
Content-Type The MIME type of the request body. Use application/json for all API interactions. Required for POST operations
Host The domain name of the server for the request. This is set by the request library in use. See Base URLs for valid values.  

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
25
26
27
28
29
POST https://sandbox.api.intuit.com/quickbooks/v4/payments/charges
Host: sandbox.api.intuit.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJlbmMiOiJBMT************nexPfzFFw
Request-Id: 1234

{
  "amount": "10.55",
  "card": {
    "expYear": "2020",
    "expMonth": "02",
    "address": {
      "region": "CA",
      "postalCode": "94086",
      "streetAddress": "1130 Kifer Rd",
      "country": "US",
      "city": "Sunnyvale"
    },
    "name": "emulate=0",
    "cvc": "123",
    "number": "4111111111111111"
  },
  "currency": "USD",
  "context": {
        "mobile": "false",
        "isEcommerce": "true"
  }
}
Common server response header fields

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

Field name Description
Cache-Control Specifies directives that must be obeyed by all caching mechanisms along the request-response chain.
Connection Control options for the current connection and list of hop-by-hop response fields.
Content-Type Defines the MIME type of the response.
Date Gives the date and time for service responses. Defined by RFC 7131 date/time format.
Expires Gives the date/time when the response is considered stale.
Keep-Alive Indicates of the HTTPS channel can be kept “alive” (open) to improve performance on subsequent requests. This is managed by the underlying networking library of the language.
Server

Specifies the server handling the request.

Tip: If there’s ever an issue, our support staff can quickly determine whether there are issues with a specific server.

Strict-Transport-Security A HSTS Policy informing the HTTP client how long to cache the HTTPS only policy, and whether this policy applies to subdomains.
Transfer-Encoding Specifies the encoding used to safely transfer the API response data to the app making the API call for the given entity. Current methods: chunked, compress, deflate, gzip, identity.

See an example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
Cache-Control : private
Connection : keep-alive
Content-Type : application/json;charset=UTF-8
Date : Wed, 31 Jan 2018 18:57:03 GMT
Expires : Wed, 31 Dec 1969 16:00:00 PST
Keep-Alive : timeout=5
Server : nginx
Strict-Transport-Security : max-age=15552000
Transfer-Encoding : chunked

{
  "created": "2018-01-31T18:48:25Z",
  "status": "SETTLED",
  "amount": "10.55",
...

}
Common QuickBooks Payments API terms and identifiers
Entity ID

This identifies individual instances of API entities such as an account, charge, or estimate. We assign this value to the entityID field.

To call entities by their entity ID, use the read operation and specify the entity ID in the URL. Use the following format and treat entity IDs as strings: baseURL/quickbooks/v4/payments/resourceName/entityID

Here’s an example:

1
baseURL/quickbooks/v4/payments/charges/EAQX3720TN5J

In this case, the entity ID for this Charge entity is EAQX3720TN5J

In a response, the ID is represented by the id attribute.


Request ID

This identifies specific HTTP requests sent from apps to our servers. Request IDs let apps correlate requests and responses.

Request IDs are especially useful in cases where apps need to resend requests due to a dropped connection, or didn’t receive a response from the server.

We strongly recommend you use request IDs for requests that write, modify, or delete data. This guarantees idempotence. If our service receives another request with the same request ID, instead of performing the operation again or returning an error, it can recognize and send the same response for the original request. This prevents duplication.

Use query parameter requestid in the URI of requests to specify request IDs.

Here are a few things to keep in mind:

This example scenario demonstrates why request IDs are important:

  1. An app sends a request to create an invoice. It specifies “4957” for the request ID like this: baseURL/company/1234/invoice?requestid=4957
  2. Our service processes the request and sends a response.
  3. The app loses its connection and doesn’t receive a response.
  4. The app sends the same request again, specifying the same content and request ID.
  5. Our server already has the requestid. It can determine that the subsequent request is the same.
  6. Our server sends the same response as in Step 2.
  7. The app receives the response and verifies it contains no errors.

If the app hadn’t specified a request ID, the server would create a duplicate invoice with a new entity ID.


Character encoding

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

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


Updating on read-only attributes

Any value supplied in a read-only attribute is transient and silently overwritten by QuickBooks data services, as appropriate to the attribute. No error is returned.

Learn more about updating read only attributes.


Timestamps and time zones

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

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

date The UTC date in the format YYYY-MM-DD.
time The UTC time in the format HH:MM:SS.
UTC offset The UTC offset to apply for time zone correction in the format +/-HH:MM.

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.


Limits and throttles

Below are limits and throttles currently in place for accessing QuickBooks Payments data services.

Multi-threading limits

Updates and additions to name list entities must be performed serially.

Updates and additions performed in a mutli-threaded enviroment may experience timing issues and lead to unexpected results.

Throttle limits

For production servers

QuickBooks Payments API endpoints are throttled at 500 requests per minute per realm ID.

For sandboxes and testing environments

Requests are throttled at 100 requests per minute per individual app.