> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hotglue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# QuickBooks Desktop

# Connector Details

| Name           | Value                                                                                                                                                                                                                                                                                                             |
| :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Platform       | [QuickBooks Desktop](https://api)                                                                                                                                                                                                                                                                                 |
| Auth Type      | On-Premise                                                                                                                                                                                                                                                                                                        |
| Direction      | Bidirectional                                                                                                                                                                                                                                                                                                     |
| Tap Metrics    | <p>Usage: <Tooltip tip="low"><Icon icon="user" iconType="regular" color="#fff" size="14px" /><Icon icon="user" iconType="regular" color="#fff" size="14px" /><Icon icon="user" iconType="regular" color="#A9A9A9" size="14px" /><Icon icon="user" iconType="regular" color="#A9A9A9" size="14px" /></Tooltip></p> |
| Target Metrics | <p>Usage: <Tooltip tip="low"><Icon icon="user" iconType="regular" color="#fff" size="14px" /><Icon icon="user" iconType="regular" color="#fff" size="14px" /><Icon icon="user" iconType="regular" color="#A9A9A9" size="14px" /><Icon icon="user" iconType="regular" color="#A9A9A9" size="14px" /></Tooltip></p> |
| Unified Schema | <Tooltip tip="Supported tables: Bills, Accounts, Vendors, Projects">Supported in [Accounting Unified Schema](https://hotglue.com/docs/unified).</Tooltip>                                                                                                                                                         |

# Overview

Quickbooks Desktop is on-premise accounting software. It is a distinct product from Quickbooks Online.

The hotglue Quickbooks Desktop connector is an installed program (.exe) that is run on the same machine that manages the Quickbooks company file. While running, the connector allows you to read and write data like you would with a normal cloud connector.

## Enable and set up your connector in hotglue

### Set up your flow

To utilize the Quickbooks Desktop connector, you first need to add Quickbooks Desktop to a flow. You only need to do this once.

1. Click `Add Flow` on the left-side toolbar.
2. Give your flow a name and description, and choose `Source Flow`.
3. After creating your flow, go to the `Sources` tab and click on Quickbooks Desktop.

If you would like to write data back to QBD, you will also need to generate a target flow. If you only need to pull data out of QBD, you can skip this step:

1. Click `Add Flow` on the left-side toolbar.
2. Give your flow a name and description, and choose `Target Flow`.
3. After creating your flow, go to the `Targets` tab and click on Quickbooks Desktop.

### Set up your tenant

Unlike cloud connectors, which offload authentication to the user, Quickbooks Desktop authentication requires you to make two API requests per tenant.

<Steps>
  <Step title="Link the tenant">
    The first request is a [POST to /linkedSources](/api-reference/v1/linked-sources/link-a-source) with a config object. This request "links" the tenant to your read flow, and creates the tenant if it doesn't already exist.

    ```bash cURL theme={null}
    curl 'https://api.hotglue.com/<ENVIRONMENT_ID>/<READ_FLOW_ID>/<TENANT_ID>/linkedSources' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <SECRET_API_KEY>' \
    --data '{
        "source": {
            "tap": "quickbooks-desktop",
            "config": {
                "company_file_name": "C:\\Users\\Public\\Documents\\Intuit\\QuickBooks\\Company Files\\hotglue.QBW",
                "tables": {
                    "account": {
                        "sync": true,
                        "replication_key": "TimeModified"
                    },
                    "bill": {
                        "sync": true,
                        "replication_key": "TimeModified"
                    }
                }
            }
        }
    }'
    ```

    <ParamField body="source" type="object" required="true">
      <Expandable body="properties" defaultOpen="true">
        <ParamField body="tap" type="string" required="true">
          `quickbooks-desktop`
        </ParamField>

        <ParamField body="config" type="object" required="true">
          <Expandable body="properties" defaultOpen="true">
            <ParamField body="company_file_name" type="string" required="true">
              The full path to the Quickbooks Desktop Company file
            </ParamField>

            <ParamField body="tables" type="array" required="true">
              Defines which tables to sync and their properties. the keys (e.g., `account`, `bill`) are table names that can be customized dynamically.

              <Expandable title="properties" defaultOpen="true">
                <ParamField body="<table>" type="string" required="true">
                  Each table can have the following fields

                  <Expandable>
                    <ParamField body="sync" type="boolean" required="true">
                      Set to `true` to sync the table.
                    </ParamField>

                    <ParamField body="replication_key" type="string">
                      Set to the datetime field you would like to incrementally fetch records based on. Usually `TimeModified` if present.
                    </ParamField>
                  </Expandable>
                </ParamField>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Step>

  <Step title="Generate the connector password">
    The next request will return the "connector password" for your configured user. Your tenant will use the connector password to authenticate their connector on their machine.

    ```
    curl 'https://api.hotglue.com/<ENVIRONMENT_ID>/<READ_FLOW_ID>/<TENANT_ID>/taps/quickbooks-desktop/token?write_flow_id=<WRITE_FLOW_ID>' \
    --header 'x-api-key: <SECRET_API_KEY>'
    ```

    <Tip>If you haven't generated a signing key before, this request will error with:
    **No signing key has been created for this environment.** To resolve, go to `Settings` > `API Keys`, and click `Generate Signing Key`. </Tip>

    Once your connector password is generated, you are ready to run the connector and start running jobs!
  </Step>

  <Step title="Optional: Enable additional Quickbooks company files">
    After you generate a config and password for one company, you can add additional company files for the connector to sync. This is done by utilizing [subtenants](https://docs.hotglue.com/key-concepts/tenants/subtenants).

    Every time the connector runs on its cycle (usually every 60 seconds), it checks if the connected tenant has subtenants. If subtenants exist, it iterates through processing for each subtenant.

    Once enabled in Settings > Widget, you can create subtenants via the syntax:

    ```
    root_tenant_id + {subtenant delimeter} + {any string}
    ```

    The default subtenant delimeter in all hotglue environments is `_`. That means if your initial `POST /linkedSources` looks like:

    ```
    /dev.hg.test.com/AAAAAA/test-user/linkedSources
    ```

    then the URL of a subtenant creation request should look like:

    ```
    /dev.hg.test.com/AAAAAA/test-user_1/linkedSources
    ```

    <Tip>**NOTE:**  Do not generate connector passwords for subtenants. Subtenants are created via new linkedSource entries (Step 1) ONLY.</Tip>
  </Step>
</Steps>

## End-user instructions

### Requirements

**1. The Quickbooks Desktop Connector and Password**

**2. QuickBooks Desktop application**

Only Windows versions are supported. You can obtain a 30-day free trial via [Intuit's website](https://quickbooks.intuit.com/desktop/enterprise/contact/trial-download/).

**3. QuickBooks SDK**

This must be downloaded on the same machine as the connector. You can install the latest from [Intuit's Website](https://developer.intuit.com/app/developer/qbdesktop/docs/get-started/download-and-install-the-sdk).

### Run the connector

<Info> The Quickbooks Desktop connector is packaged as a .exe file. It is signed with an Extended Validation Code Signing Certificate issued by Sectigo, meaning it is verified and cannot be tampered with. </Info>
<Warning> Make sure Quickbooks Desktop is open and you are logged in to the Company File as an Administrator User before running the Quickbooks Desktop Connector</Warning>

<Steps>
  <Step title="Download the connector launcher file." />

  <Step title="(Optional) Move the connector launcher to your startup folder">
    This ensures that the connector runs automatically when you restart your machine. To configure this:

    1. Right click the windows icon on the bottom left
    2. Select `run`, then type `shell:startup` > OK
    3. This will open your startup folder. Drag the launcher from your downloads folder to here.
  </Step>

  <Step title="Run the connector launcher">
    Right-click > `Run as administrator`
  </Step>

  <Step title="Enter the connector password">
    After the connector boots up, you will see a dialog requesting the connector password. Enter the password.
  </Step>
</Steps>

If the pop-up closes, that means the password is accepted, the connector is installed, and you are ready to begin syncing data.

# Connector Capabilities

The QuickBooks Desktop connector supports both read and write. Learn more below.

## Read

To read data from QuickBooks Desktop, you simply configure the `tables` section in the config. A list of supported objects for read is provided below.

### Supported Objects

* account
* balance\_sheet\_detail
* balance\_sheet\_summary
* bill
* check
* class
* credit\_memo
* customer
* estimates
* invoice
* item
* item\_sales\_tax
* journal\_entry
* price\_level
* profit\_and\_loss
* profit\_and\_loss\_budget
* purchase\_order
* sale\_order
* sales\_receipt
* sales\_tax\_code
* transaction\_list
* unit\_of\_measure\_set
* vendor

## Write

The QuickBooks Desktop connector also supports writing objects, using JSON files that follow the [qbXML raw schema](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop).

<Info> When writing data to QuickBooks Desktop, ensure that the `.json` files are written to the `etl-output` folder in your jobs. Otherwise the connector will not process them. </Info>

### File Formatting

Currently the connector supports only `JSON` files, and must follow the following criteria:

* Files must be named following the convention `<object>(-<suffix>).json`, where:
  * `<object>` is the lowercase name of the connector object (e.g., `customer`, `invoice`)
  * `-<suffix>` is optional and can be any descriptive string (e.g., `-may`, `-20250715`)

| **✅ Valid File Names**   | **❌ Invalid File Names** |
| ------------------------ | ------------------------ |
| `customer.json`          | `Customer.json`          |
| `customer-may.json`      | `CustomerAddRq.json`     |
| `customer-20250715.json` |                          |

* All keys in the JSON file must appear in **exactly** the same order as shown in the official qbXML documentation. For example:

<CodeGroup>
  ```json invoice-valid.json ✅ theme={null}
  [
      {
          "CustomerRef": {
              "FullName": "EAST NEW YORK HARDWARE"
          },
          "RefNumber": "00026420",
          "InvoiceLineAdd": [
              {
                  "ItemRef": {
                      "FullName": "NFR-SH86150"
                  },
                  "Quantity": "1",
                  "Amount": "100.00"
              }
          ]
      }
  ]
  ```

  ```json invoice-invalid.json ❌ theme={null}
  [
      {
        "InvoiceLineAdd": [
              {
                  "ItemRef": {
                      "FullName": "NFR-SH86150"
                  },
                  "Quantity": "1",
                  "Amount": "100.00"
              }
          ],
          "CustomerRef": {
              "FullName": "EAST NEW YORK HARDWARE"
          },
          "RefNumber": "00026420"
      }
  ]
  ```
</CodeGroup>

### Supported Objects

Below is a list of Hotglue QBD connector object names, and the corresponding qbXML requests that they use.

| Connector Object Name | qbXML Request                                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `customer`            | [CustomerAddRq](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/customeradd)                 |
| `invoice`             | [InvoiceAddRq](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/invoiceadd)                   |
| `bill`                | [BillAddRq](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/billadd)                         |
| `sales_order`         | [SalesOrderAddRq](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/salesorderadd)             |
| `credit_memo`         | [CreditMemoAddRq](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/creditmemoadd)             |
| `vendor`              | [VendorAddRq](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/vendoradd)                     |
| `vendor_credit`       | [VendorCreditAddRq](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/vendorcreditadd)         |
| `item_inventory`      | [ItemInventoryAddRq](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/iteminventoryadd)       |
| `item_noninventory`   | [ItemNonInventoryAddRq](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/itemnoninventoryadd) |
| `sales_receipt`       | [SalesReceiptAddRq](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/salesreceiptadd)         |
| `journal_entry`       | [JournalEntryAddRq](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/journalentryadd)         |
| `item_sales_tax`      | [ItemSalesTaxAddRq](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/itemsalestaxadd)         |