Core concepts

QuickBooks Desktop runs on your customer’s Windows computer, not in the cloud. Everything in this API follows from that fact: requests wait in a queue until the customer’s computer picks them up, the computer can be off, and QuickBooks itself can be busy. These are the objects you work with.

Organization ── Project (test or production) ─┬─ Secret keys, publishable key
                                               ├─ Webhook endpoints
                                               └─ End users ── Connection ─┬─ Connectors (Web Connector installs)
                                                                           ├─ Requests
                                                                           └─ Company file

Organization

Your company’s account. It holds team members, roles and billing. Members are owners, admins or members. Owners manage billing and roles; owners and admins manage projects and keys; members work with end users, setup links and the request log.

Project

An isolated environment inside the organization, for example “Development” and “Production”. A project’s environment is either test or production and is fixed when you create it.

• Test projects are free and use sk_test_ and pk_test_ keys. Use them with sample company files and trial installations of QuickBooks.
• Production projects use sk_live_ and pk_live_ keys and are billed per active company file. See Billing and pricing.

A key only reaches end users in its own project. Two projects never share data.

Secret key and publishable key

A secret key (sk_test_... or sk_live_...) authenticates every API call from your server. A project can have many named secret keys, so you can rotate them. The publishable key (pk_...) is a public project identifier that you pass when you create setup links. See Authentication.

End user

Your customer, as seen by the API. An end user has your own identifier (sourceId), a company name that the setup flow shows, and a contact email for your records. We never email end users.

Create one end user per QuickBooks company file. If a customer keeps two company files, create two end users.

Connection

The link between an end user and one QuickBooks company file. It has a status (pending_setup, online, offline, quickbooks_unavailable, company_file_mismatch, disabled), the company name and QuickBooks version it last saw, and the queue of requests waiting for that file. The end user object returns it in integrationConnections.

Connector

One installation of the QuickBooks Web Connector that serves a connection: one .qwc file, one Web Connector username and one password. A connection usually has one connector. When your customer moves to a new computer and runs setup again, the new computer gets a new connector and the old one is turned off once the new one works.

Auth session and the setup flow

An auth session is a time-limited setup link (authFlowUrl) for one end user. The person at the QuickBooks computer opens it and follows five short steps: download the connector file, allow access in QuickBooks, enter the password in the Web Connector and wait for the live check. See Connect an end user.

Request

Every call that needs QuickBooks, such as listing invoices, creating a customer, a health check or passthrough, becomes a request with an ID like req_01j9.... A request moves through statuses: queued, then sent to the Web Connector, then succeeded or failed. You can read any request back with GET /v1/requests/{id}, and the dashboard request log shows its timeline. See Request lifecycle.

Platform calls such as creating an end user also return a request ID for support, but they never queue.

The QuickBooks Web Connector

Intuit’s free Windows program that lets web services talk to QuickBooks Desktop. It polls our server over HTTPS. Our connector file tells it to check in every 10 seconds, and more often while there is work. When a request is waiting, the Web Connector opens a session with QuickBooks, passes the request in and sends QuickBooks’ answer back. Nothing listens on your customer’s network, and their firewall needs no inbound rules.

Because the Web Connector polls, the first request after a quiet period waits for the next check-in. Follow-up requests in the same session are fast. Request lifecycle has the numbers.

QuickBooks objects

QuickBooks records come in two families, and the API keeps that split:

• Lists: customers, vendors, items, accounts, classes, terms and similar. They have a name and fullName, can be hierarchical (Parent:Child), and are deactivated with isActive: false instead of deleted.
• Transactions: invoices, bills, checks, payments, journal entries and others. They have a transactionDate, often a refNumber and line items, and they can be deleted and, for most types, voided.

Every QuickBooks object has a QuickBooks-assigned id and a revisionNumber that changes on each edit. You need the current revisionNumber to update an object. See Updates and line items.