Supported environments

QuickBooks Desktop

Product	Supported
QuickBooks Desktop Enterprise Solutions, every industry edition	Releases that support qbXML 13.0 or newer (2014 and later)
QuickBooks Desktop Premier, Premier Accountant, Accountant, including Plus	2018 and later
QuickBooks Desktop Pro, including Plus	2018 and later
QuickBooks Desktop for Mac	No (it has no Web Connector)
Canadian, UK and Australian editions	No. Calls return 422 QBD_REGION_UNSUPPORTED
QuickBooks Online	No. This API is for QuickBooks Desktop only
QuickBooks Point of Sale	No

Fields and operations that need a newer qbXML version than the customer’s QuickBooks supports are rejected before sending, with QBD_FIELD_UNSUPPORTED_BY_VERSION. See Editions, versions and features.

Our Windows end-to-end tests run on QuickBooks Desktop Enterprise 24.0 R21 (US) with the classic Web Connector 34.0.10010.76 on Windows 10 Pro (build 19045). The other editions and versions in the table are supported through the qbXML version checks above.

The customer’s computer

• Windows: a Windows version that the customer’s QuickBooks release supports.
• QuickBooks Web Connector: the classic Web Connector 2.2.0.34 or newer, which supports TLS 1.2. Recent QuickBooks releases install it. We recommend the build that matches the newest QuickBooks installed.
• Always on: the computer must be on, with the Windows user who set up the connection signed in and the Web Connector running. A locked screen is fine.
• One QuickBooks version installed on the computer that runs the Web Connector.
• First authorization: signed in to QuickBooks as Admin, company file in single-user mode. Multi-user mode is fine afterwards.
• One company file at a time: QuickBooks opens one company file at a time on a computer, so connections to different company files on the same computer take turns. Only the connection whose file is open can answer. See Connect several company files.

Exiting the Web Connector during an update

Choosing File › Exit in the Web Connector while an update is running can leave it stuck partway through closing. QuickBooks then refuses to close the company file, exit or restore a backup, because it still counts the app as using the file. Ending the stuck Web Connector in Task Manager releases the file, but not at once: in our tests QuickBooks let go of the file between 6 and 12 minutes after the Web Connector stopped or was ended. The end-user page QuickBooks says the company file is being used by another application gives the recovery steps. Customers avoid the problem by unchecking Auto-Run for the app and waiting 15 seconds before they exit the Web Connector or close the company file.

Network

The Web Connector makes outbound HTTPS requests (port 443) to qbwc.desktopaccountingapi.com. The setup flow runs at connect.desktopaccountingapi.com. Nothing connects in to the customer’s network, so no firewall or router changes are needed. HTTPS inspection by antivirus or proxies can break the connection (QBWC1012, QBWC1048).

Hosting

Setup	Supported
QuickBooks on a desktop PC	Yes
Multi-user office, file on a server	Yes. Run the Web Connector on a computer with full QuickBooks that can open the file and stays on. See Use the connection in a multi-user office
Hosted QuickBooks (Rightworks and similar)	Yes, where the provider lets the Web Connector run in a session that stays signed in. See Hosted QuickBooks
Windows virtual machines and cloud desktops	Yes, under the same always-on rules

Your side

• Any language that can make HTTPS requests. SDKs for TypeScript, Python, C# / .NET and Java.
• Call the API from your servers. Browsers cannot call it (no CORS), so keys never reach a client.

Documented incompatibilities

QuickBooks Desktop cannot do everything comparable APIs offer, and some features depend on the edition or the company’s settings. Each case below says what the API does, which error you get and what to do instead. The API answers unsupported operations with 422 QBD_OPERATION_UNSUPPORTED and alternatives rather than a bare 404. This list is generated from the same registry the API uses.

POST /v1/quickbooks-desktop/sales-tax-payment-checks/{id}/void is not available

QuickBooks Desktop's SDK has no void request for SalesTaxPaymentCheck (it is not a qbXML TxnVoidType), so the operation is not offered.

What the API does. The API answers 422 QBD_OPERATION_UNSUPPORTED with details.alternatives; nothing is sent to QuickBooks. See QBD_OPERATION_UNSUPPORTED.

Instead

• DELETE /v1/quickbooks-desktop/sales-tax-payment-checks/{id} deletes the transaction instead.
• Void it in the QuickBooks Desktop window.

Operations: qbd.salesTaxPaymentChecks.void

Payroll wage items list without cursor pagination

qbXML declares no iterator for the payroll wage item query, so the list cannot be paged with a cursor. Conductor documents cursor pagination for this list.

What the API does. The list returns every matching record in one page with nextCursor null, hasMore false and remainingCount 0, so a Conductor pagination loop stops after it. A cursor parameter returns 400 CURSOR_INVALID: there is never one to send.

Instead

• Use limit and the name filters to narrow the result.

Operations: qbd.payrollWageItems.list

Small lists return every record

These QuickBooks queries have no iterator. They are small configuration lists in practice.

What the API does. The list returns every matching record without cursor fields (x-daapi-pagination: none), except templates.list, which returns nextCursor null, hasMore false and remainingCount 0 because Conductor pages it. Where QuickBooks supports it, limit caps the count.

Instead

• Use the operation filters to narrow large results.

Operations: qbd.accountTaxLines.list, qbd.accounts.list, qbd.billsToPay.list, qbd.classes.list, qbd.currencies.list, qbd.customerTypes.list, qbd.dateDrivenTerms.list, qbd.deletedListObjects.list, qbd.deletedTransactions.list, qbd.employees.list, qbd.inventoryAdjustments.list, qbd.inventorySites.list, qbd.otherNames.list, qbd.paymentMethods.list, qbd.paymentsToDeposit.list, qbd.priceLevels.list, qbd.salesRepresentatives.list, qbd.salesTaxCodes.list, qbd.shippingMethods.list, qbd.standardTerms.list, qbd.templates.list, qbd.unitOfMeasureSets.list

Inventory sites need Advanced Inventory

Multiple inventory sites, item sites, site transfers and site or bin fields on transactions exist only in QuickBooks Desktop Enterprise with an active Advanced Inventory subscription and multiple inventory locations turned on.

What the API does. QuickBooks rejects the request; the API returns 422 QBD_FEATURE_NOT_ENABLED (qbXML status 3250). See QBD_FEATURE_NOT_ENABLED.

Instead

• Read the company preferences before offering site features.
• Omit site fields for company files without Advanced Inventory.

Operations: qbd.inventorySites.list, qbd.inventorySites.create, qbd.inventorySites.retrieve, qbd.inventorySites.update, qbd.itemSites.list, qbd.itemSites.retrieve, qbd.transfers.list, qbd.transfers.create, qbd.transfers.retrieve, qbd.transfers.update

Sales orders need Premier or above

QuickBooks Desktop Pro has no sales orders; Premier, Accountant and Enterprise do, with sales orders turned on in Preferences.

What the API does. QuickBooks rejects the request; the API returns 422 QBD_FEATURE_NOT_ENABLED, or QBD_REQUEST_ERROR with the native status. See QBD_FEATURE_NOT_ENABLED.

Instead

• Use estimates or invoices on Pro.

Operations: qbd.salesOrders.list, qbd.salesOrders.create, qbd.salesOrders.retrieve, qbd.salesOrders.update, qbd.salesOrders.delete

Inventory assemblies need Premier or above

Inventory assembly items and assembly builds are not available in QuickBooks Desktop Pro.

What the API does. QuickBooks rejects the request; the API returns 422 QBD_FEATURE_NOT_ENABLED, or QBD_REQUEST_ERROR with the native status. See QBD_FEATURE_NOT_ENABLED.

Instead

• Use group items on Pro.

Operations: qbd.inventoryAssemblyItems.list, qbd.inventoryAssemblyItems.create, qbd.inventoryAssemblyItems.retrieve, qbd.inventoryAssemblyItems.update, qbd.buildAssemblies.list, qbd.buildAssemblies.create, qbd.buildAssemblies.retrieve, qbd.buildAssemblies.update, qbd.buildAssemblies.delete

Units of measure need Premier or above

Unit of measure sets exist in Premier, Accountant and Enterprise with the unit of measure preference turned on.

What the API does. QuickBooks rejects the request; the API returns 422 QBD_FEATURE_NOT_ENABLED. See QBD_FEATURE_NOT_ENABLED.

Instead

• Send quantities in the base unit of the item.

Operations: qbd.unitOfMeasureSets.list, qbd.unitOfMeasureSets.create, qbd.unitOfMeasureSets.retrieve

Per-item price levels need Premier or above

QuickBooks Desktop Pro supports only fixed-percentage price levels; per-item price levels need Premier or above. Price levels must be turned on in Preferences.

What the API does. QuickBooks rejects per-item price levels; the API returns 422 QBD_FEATURE_NOT_ENABLED or QBD_REQUEST_ERROR. See QBD_FEATURE_NOT_ENABLED.

Instead

• Use fixed-percentage price levels on Pro.

Operations: qbd.priceLevels.create, qbd.priceLevels.update

Currencies need multicurrency turned on

Currency records and foreign amounts exist only after the company turns on multicurrency, which QuickBooks cannot undo.

What the API does. QuickBooks rejects the request; the API returns 422 QBD_FEATURE_NOT_ENABLED. See QBD_FEATURE_NOT_ENABLED.

Instead

• Check the multicurrency preference before using currency fields.

Operations: qbd.currencies.list, qbd.currencies.create, qbd.currencies.retrieve, qbd.currencies.update

Payroll data needs QuickBooks payroll

Payroll items and payroll reports depend on QuickBooks payroll being set up in the company file. Wage amounts that Intuit marks private are not returned.

What the API does. Without payroll, queries return empty results or QBD_FEATURE_NOT_ENABLED. See QBD_FEATURE_NOT_ENABLED.

Operations: qbd.payrollWageItems.list, qbd.payrollWageItems.create, qbd.payrollWageItems.retrieve, qbd.reports.payrollDetail, qbd.reports.payrollSummary

Payroll wage item rates cannot be written

rate, ratePercent and overtimeMultiplier are elements Intuit marks private. On QuickBooks Desktop Enterprise 24 (Windows E2E run 6), wage items created with them were saved without the values: neither the add response nor a native PayrollItemWageQuery returned them. Conductor accepts these fields on create.

What the API does. Sending them on create returns 400 UNKNOWN_PARAMETER naming the field; nothing is sent. They stay in responses and are null unless QuickBooks returns them. See UNKNOWN_PARAMETER.

Instead

• Create the wage item without rates, then set the rate on each employee's earnings in QuickBooks.

Operations: qbd.payrollWageItems.create

Social Security numbers and full card numbers are not available

Every connection is authorized with the Web Connector personal-data preference "not needed", so QuickBooks never returns SSNs or full credit card numbers to the integration and the setup flow does not ask the end user for personal-data access.

What the API does. Those fields are absent from responses and not accepted in requests.

Instead

• Collect such data outside QuickBooks if your application needs it.

Operations: qbd.employees.list, qbd.employees.retrieve, qbd.employees.create, qbd.employees.update

Payroll reports need personal-data access

QuickBooks treats payroll reports as personal data. Connections are authorized without personal-data access, so QuickBooks Enterprise 24 rejects these reports with status 3261 until the QuickBooks Admin allows it for the application in the Integrated Applications preferences.

What the API does. The API returns 403 QBD_INSUFFICIENT_PERMISSION with integrationCode 3261 and the steps for the QuickBooks Admin. See QBD_INSUFFICIENT_PERMISSION.

Instead

• Ask the QuickBooks Admin to allow personal-data access: Edit > Preferences > Integrated Applications > Company Preferences, select the application, Properties.
• Use the general summary and detail reports, which do not need personal-data access.

Operations: qbd.reports.payrollDetail, qbd.reports.payrollSummary

Only US editions of QuickBooks Desktop

Canadian, UK and Australian editions use different qbXML schemas (tax models, payroll, fields).

What the API does. Resource operations return 422 QBD_REGION_UNSUPPORTED for a non-US company file; passthrough stays available at your own risk. See QBD_REGION_UNSUPPORTED.

Instead

• Use passthrough with the qbXML of that edition.

Fields introduced in newer qbXML versions

Each field carries the qbXML version that introduced it. QuickBooks releases older than that version do not know the field.

What the API does. Sending a newer field to an older QuickBooks returns 422 QBD_FIELD_UNSUPPORTED_BY_VERSION with details.minimumQbxmlVersion before anything is sent. See QBD_FIELD_UNSUPPORTED_BY_VERSION.

Instead

• Check the connection companyFile.qbxmlVersion before sending newer fields.

Other differences by design:

• List objects are deactivated, not deleted through the typed API. Use isActive: false, or delete through passthrough with ListDel when you must.
• References by name are not accepted on input; send IDs. See references.
• qbXML messages without typed operations, such as ListDel, DataExt*, ToDo*, VehicleMileage*, TransferInventory*, BillingRate*, JobType* and VendorType*, are available through passthrough.