# QuickBooks

> Bring invoices, customers, items, payments, accounts and journal entries from QuickBooks Online into your warehouse.

## Before you start

sanda connects to QuickBooks Online, not QuickBooks Desktop. The form asks for a full set of OAuth credentials: an app's client ID and secret, plus tokens for your company. You get all of them from Intuit's developer portal.

- **An Intuit developer account.** Create an app in the developer portal, with the accounting scope (`com.intuit.quickbooks.accounting`).
- **Keys for the right environment.** Each app has development keys and production keys. Use production keys for a live company, and development keys with **Sandbox** turned on for a sandbox company. Intuit may ask you to complete a short questionnaire about the app before it issues production keys.
- **Tokens for your company.** In the developer portal, use the OAuth 2.0 Playground. Choose your app, select the accounting scope, and authorise it against your company. The Playground then shows an access token and a refresh token, and its **Make API Calls** panel shows the realm ID, which QuickBooks also labels the Company ID.

Use tokens generated only for sanda. Intuit can issue a new refresh token each time one is used, so two tools sharing one set of tokens can lock each other out.

## Connect QuickBooks

:::steps
1. **Choose QuickBooks.** Go to **Data · Connections**, press **New connection** and pick **QuickBooks**.
2. **Identify the company.** Put the realm ID in **Realm ID**. The field is masked, like a password.
3. **Enter the app's keys.** Put the app's client ID in **Client ID** and its client secret in **Client Secret**.
4. **Enter the tokens.** Paste the access token into **Access Token** and the refresh token into **Refresh Token**. Intuit access tokens last one hour, so enter that expiry in **Token Expiry Date**, as a UTC date and time such as `2026-09-30T05:00:00Z`.
5. **Choose how far back to load.** Enter a UTC date and time in **Start Date**, in the form `2021-03-20T00:00:00Z`. Data before it is not replicated.
6. **Check the environment.** **Sandbox** sits under **Advanced settings** and opens off, which is right for a live company. Turn it on for a sandbox company.
7. **Continue.** Press **Continue**, name the connection, and press **Read schema**. sanda signs in and lists the QuickBooks objects it can read. If it fails, the message says why. See [Troubleshoot connections](https://docs.sanda-os.com.au/connections/troubleshooting).
:::

The rest of the flow, naming the connection, setting a frequency and choosing streams, is the same for every source. See [Add a connection](https://docs.sanda-os.com.au/connections/add-a-connection).

## What syncs

Each QuickBooks object becomes a stream, and lands in your warehouse as its own table. The usual starting points are invoices, customers, items, payments, accounts and journal entries. The stream list shows everything the connection can read, and you choose which to sync. See [choose what to sync](https://docs.sanda-os.com.au/connections/choose-streams).

## Tips

- **Refresh tokens expire.** Intuit's refresh tokens expire after 100 days without use. A connection that has been paused for months may need new tokens from the Playground.
- **One connection per company.** A realm ID belongs to one QuickBooks company. For several companies, add a connection for each and give each a distinct name, for example `Acme · QuickBooks (AU)`. The name decides the tables the rows land in.
- **Live and sandbox do not mix.** Production keys only work against live companies, and development keys against sandbox ones. A mismatch fails at **Read schema**.
- **A later Start Date shortens the first load.** The first run reads everything from **Start Date** onward.

## Configuration fields

What the connection form asks for. Required fields are marked; the rest are optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **Realm ID** | string, secret | Yes | Labeled Company ID. The Make API Calls panel is populated with the realm id and the current access token. |
| **Client ID** | string | Yes | Identifies which app is making the request. Obtain this value from the Keys tab on the app profile via My Apps on the developer site. There are two versions of this key: development and production. |
| **Access Token** | string, secret | Yes | Access token for making authenticated requests. |
| **Client Secret** | string, secret | Yes | Obtain this value from the Keys tab on the app profile via My Apps on the developer site. There are two versions of this key: development and production. |
| **Refresh Token** | string, secret | Yes | A token used when refreshing the access token. |
| **Token Expiry Date** | string | Yes | The date-time when the access token should be refreshed. |
| **Start Date** | string | Yes | The default value to use if no bookmark exists for an endpoint (rfc3339 date string). E.g, 2021-03-20T00:00:00Z. Any data before this date will not be replicated. |
| **Sandbox** | boolean | Yes | Determines whether to use the sandbox or production environment. Default `false`. |

## Related

:::links
- [Sync modes](https://docs.sanda-os.com.au/connections/sync-modes): How sanda reads each stream on every run.
- [Sync schedules](https://docs.sanda-os.com.au/connections/schedules): How often a connection runs.
- [Allowlist sanda’s address](https://docs.sanda-os.com.au/connections/allowlist): For a system behind a firewall.
- [Troubleshoot connections](https://docs.sanda-os.com.au/connections/troubleshooting): What an error means and how to fix it.
:::