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

# QuickBooks Online

> Connect QuickBooks Online to Stuut by signing in to Intuit from the Stuut dashboard.

Stuut connects to QuickBooks Online with OAuth 2.0. You sign in to Intuit from Stuut, choose the company to connect, and approve access. There are no keys to copy and nothing to install in QuickBooks.

Once connected, Stuut imports your customers, invoices, credit memos, payments and chart of accounts, and keeps them up to date every hour. If you use Stuut Cash Application, payments you approve in Stuut are posted back to QuickBooks.

This guide covers QuickBooks Online only. QuickBooks Desktop uses a different Stuut connector.

**Estimated time:** about 5 minutes

## Before you begin

You will need:

* A QuickBooks Online user who is the **Primary admin** or a **Company admin**. Intuit only lets admins connect apps; standard users, custom roles and reports-only users can't.
* A Stuut administrator account.
* Pop-ups allowed for your Stuut dashboard. Intuit's sign-in opens in a pop-up window.

Each connection covers one QuickBooks company. If you run several companies, connect each one separately.

## What access Stuut asks for

On Intuit's screen, Stuut requests two things:

| Intuit permission | What it is for |
| - | - |
| QuickBooks Online **Accounting** | Reading the data listed below, and creating payments when you approve them in Stuut |
| **OpenID** | Identifying the Intuit user who signed in |

Intuit grants Accounting access as a whole and does not offer a read-only version, so the consent screen describes broader access than Stuut uses. What Stuut actually reads and writes is listed in the next two sections. Stuut does not request access to QuickBooks Payments or Payroll.

## What Stuut reads

| Data | What Stuut reads |
| - | - |
| Customers | Display name, first and last name, email address, phone number, currency, and the parent customer for sub-customers |
| Contacts | QuickBooks has no separate contact records. If a customer's email field holds several addresses, the first becomes the customer's email and each of the others becomes a billing contact in Stuut. |
| Invoices | Number, invoice date, due date, currency, amounts (subtotal, discount, tax, total and amount paid), line items (description, quantity, rate, amount), billing email, billing address, the message on the invoice, and the online payment link if the invoice has one |
| Invoice PDFs | A PDF of each invoice, so Stuut can attach it to reminder emails |
| Credit memos | Number, date, currency, amounts (discount, tax, total and amount applied), line items, and the message on the credit memo |
| Payments | Reference number, date, amount, currency, memo, and the invoices and credit memos each payment is applied to |
| Chart of accounts | Name, number, type, detail type, active flag and parent account. Stuut uses these for Cash Application: the deposit account on a payment and the accounts for deductions. |

A few things to know:

* **Invoice status comes from the balance.** An invoice with a balance is open in Stuut. An invoice with a zero balance shows as paid, and so does a voided invoice or an invoice with a zero total. Stuut does not show a separate void or draft status for QuickBooks invoices.
* **Amount paid** is the invoice total minus its open balance, so it includes credit memos applied to the invoice as well as payments.
* **Deleted invoices are removed.** On each sync Stuut checks a batch of invoices against QuickBooks and removes any that no longer exist there.
* **Multicurrency is supported.** Each record keeps the currency QuickBooks gives it. In a company without multicurrency, Stuut uses the company's home currency.
* **Custom fields are not imported by default**, and neither is a purchase order number held in an invoice custom field. If you need either in Stuut, ask your Stuut contact; they are set up per organization.
* Stuut does not import estimates, sales receipts, refund receipts, statements, vendors, bills or products and services.

## What Stuut writes

Stuut never edits or deletes customers, invoices, credit memos or accounts in QuickBooks.

Stuut writes to QuickBooks in one case: when a payment is approved in Stuut Cash Application. If you use Stuut for Collections only, nothing is ever written.

For each approved payment, Stuut creates one **Receive Payment** in QuickBooks:

| QuickBooks field | What Stuut sends |
| - | - |
| Customer | The customer on the payment |
| Amount received | The cash amount of the payment |
| Payment date | The payment date in Stuut |
| Reference no. | The bank reference, shortened to 21 characters (QuickBooks' limit). If there is none, the Stuut payment ID. |
| Memo | `Stuut payment` followed by the Stuut payment ID |
| Deposit to | The QuickBooks account mapped to the Stuut bank account the money arrived in. If no account is mapped, Stuut leaves this blank and QuickBooks applies its own default. |
| Outstanding transactions | Each invoice the payment is applied to, for the applied amount |
| Credits | Each credit memo applied on the payment |

Any part of the payment that is not applied to an invoice stays on the QuickBooks payment as unapplied customer credit.

### Deductions and other adjustments

If the payment includes adjustments, for example a short-pay deduction or a surcharge, Stuut also creates one **journal entry**:

* Each adjustment posts to the QuickBooks account mapped to that adjustment type in Stuut. A deduction debits its account and a surcharge credits it.
* The net of the adjustments posts to Accounts Receivable against the customer, and the payment is applied to that journal entry alongside the invoices.
* The journal entry number starts with `SA` and its memo reads `Stuut payment adjustments` followed by the Stuut payment ID.

For adjustments to post:

* Every adjustment type used on the payment must be mapped to a QuickBooks account. Stuut checks this when you approve the payment and tells you which one is missing.
* The payment must be applied to at least one invoice.
* QuickBooks must have exactly one active Accounts Receivable account in the payment's currency.

### What Stuut will not post

Stuut refuses the following and shows the reason on the payment in Stuut:

* A **\$0 payment**. QuickBooks does not accept one.
* A payment applied to an invoice or credit memo that has **not synced** from QuickBooks yet. Run a sync and approve it again.
* A payment whose applied amounts add up to **more than the payment**.

Before creating anything, Stuut looks in QuickBooks for a payment with the same reference number and customer. If one is already there, Stuut links to it instead of creating a second one.

If you would rather Stuut never post payments to QuickBooks, ask your Stuut contact to turn write-back off for your organization.

## How often Stuut syncs

* **Every hour**, Stuut fetches records that were created or changed in QuickBooks since the last sync, in this order: chart of accounts, customers, invoices, credit memos, payments.
* **On demand:** click **Sync** on the connection at any time.

Intuit limits how fast any app can call a QuickBooks company. During a large import, and while invoice PDFs download in particular, you may see failed requests on the connection's **Logs** tab and a model waiting to retry. Stuut waits and retries on its own; you don't need to do anything.

## Set up the connection

### 1. Open the QuickBooks Online connector in Stuut

In Stuut, go to **Settings → Connectors → All connectors**, search for **QuickBooks**, and click **Add** next to **Quickbooks Online**.

### 2. Start the connection

Stuut shows **Connect to QuickBooks Online**. Click **Continue**.

![Stuut dialog titled Connect to QuickBooks Online with a Continue button](https://mintcdn.com/stuut-support/pzgwzVA98HcAD7bc/images/quickbooks-online/connect-dialog.png?fit=max\&auto=format\&n=pzgwzVA98HcAD7bc\&q=85\&s=e8ec0c8139326a44e61045b002d5327e)

The first step of the QuickBooks Online connect dialog

Stuut confirms the integration has been created. Click **Continue** again.

### 3. Sign in to Intuit and approve access

Stuut shows **Authorize Quickbooks Online**. Click **Open window**.

![Stuut dialog titled Authorize Quickbooks Online with an Open window button](https://mintcdn.com/stuut-support/pzgwzVA98HcAD7bc/images/quickbooks-online/authorize-dialog.png?fit=max\&auto=format\&n=pzgwzVA98HcAD7bc\&q=85\&s=018ae3e43b15a50a0bdf4b260456b3a0)

Open the Intuit sign-in window

A pop-up opens on Intuit's sign-in page, and the Stuut dialog shows **Waiting for authorization** until you finish. You have three minutes before Stuut cancels the attempt; if that happens, click **Open window** again.

In the pop-up:

1. Sign in with your QuickBooks admin user. If you're already signed in to Intuit in the same browser, Intuit skips this step.
2. If your Intuit login has access to more than one company, choose the company to connect.
3. Review the access Stuut asks for and click **Connect**.

The pop-up closes on its own and Stuut shows **QuickBooks Online connected**. Click **Continue**.

### 4. Run the first sync

Stuut opens the connection, which shows a **Linked** badge. Click **Sync** to start the first import right away rather than waiting for the next scheduled one.

The **Overview** tab lists the **Credit Memos**, **Customers**, **Invoices**, **Ledger Accounts** and **Payments** models. Each one shows **Done** when its import has finished, along with the time of the next sync.

![Quickbooks Online connection with a Linked badge and five models showing a Done sync status](https://mintcdn.com/stuut-support/pzgwzVA98HcAD7bc/images/quickbooks-online/connection-overview.png?fit=max\&auto=format\&n=pzgwzVA98HcAD7bc\&q=85\&s=a1b55b080f996a646359b8a2b180d38b)

The connection after the first sync

There are no settings to choose for QuickBooks Online during setup.

## Manage the connection

Open **Settings → Connectors → Connected apps** and select **Quickbooks Online**.

* **Check health** confirms Stuut can still read your QuickBooks company.
* **Sync** starts a sync now instead of waiting for the next hourly one.
* **Logs** lists every request Stuut made to QuickBooks, with its status.
* **Settings → Connection name** gives the connection a friendly name, which helps when you have connected more than one company.
* **Settings → Delete integration** disconnects QuickBooks. Stuut revokes its own access at Intuit and deletes the customers, invoices and other data it imported from that company. Payments Stuut already posted stay in QuickBooks.

## Troubleshooting

> [accordion] Nothing happens when I click Open window
>
> Your browser blocked the pop-up. Allow pop-ups for your Stuut dashboard and try again.

> [accordion] Intuit says I need admin permissions to connect
>
> You are signed in to Intuit as a user who is not an admin of that company. Have the Primary admin or a Company admin make the connection, or ask them to make you a Company admin first.

> [accordion] The models still show no sync status after connecting
>
> Click **Sync** on the connection. Each model moves to **Queued** and then **Done**.

> [accordion] Failed requests or a model waiting to retry during the first import
>
> Intuit is limiting how fast Stuut can call your company. Stuut retries on its own and the model finishes a minute or two later. If a model is still not **Done** after an hour, contact Stuut support.

> [accordion] Check health fails on a connection that used to work
>
> Intuit stopped accepting Stuut's access. The usual causes are that someone disconnected Stuut from the company's connected apps in QuickBooks, or that the connection was not used for 100 days. Intuit also requires every connection to be approved again after five years. Contact Stuut support to reconnect without losing synced data.

> [accordion] A payment approved in Stuut did not appear in QuickBooks
>
> Open the payment in Stuut; the posting error is shown on it. The common causes are an adjustment type with no QuickBooks account mapped, an invoice that has not synced yet, or more than one active Accounts Receivable account in the payment's currency when the payment has adjustments.

> [accordion] A voided invoice shows as paid in Stuut
>
> This is expected. QuickBooks reports a voided invoice with a zero balance, and Stuut treats any zero-balance invoice as paid, so it drops out of collections either way.

## Security

* Stuut connects over HTTPS and stores QuickBooks access tokens encrypted at rest.
* Intuit never shares your password with Stuut. You sign in on Intuit's own page.
* You can remove Stuut's access at any time, either with **Delete integration** in Stuut or by disconnecting Stuut from your connected apps in QuickBooks.

For security questions, contact [security@stuut.co](mailto:security@stuut.co).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.