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

# QuickBooks

> Integration details and setup guide for the QuickBooks connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                                                                                                                                                                             |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authentication**                  | OAuth 2.0 (Authorization Code with refresh tokens)                                                                                                                                                  |
| **Two-Way Sync**                    | Yes                                                                                                                                                                                                 |
| **Events Supported**                | Yes (Webhooks)                                                                                                                                                                                      |
| **Realtime**                        | Yes                                                                                                                                                                                                 |
| **Supports Rate Limiting**          | Yes (500 requests per minute per app)                                                                                                                                                               |
| **Authentication Scopes Supported** | `com.intuit.quickbooks.accounting` (accounting data), `openid` (OpenID), `email` (email information), `profile` (profile information), `address` (address information), `phone` (phone information) |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **QuickBooks**:

* **Account**
* **Bill**
* **BillPayment**
* **Class**
* **CompanyInfo**
* **CreditMemo**
* **Customer**
* **Deposit**
* **Employee**
* **Estimate**
* **Invoice**
* **Item**
* **JournalEntry**
* **Payment**
* **PaymentMethod**
* **Purchase**
* **PurchaseOrder**
* **RefundReceipt**
* **SalesReceipt**
* **TaxCode**
* **TaxRate**
* **Term**
* **TimeActivity**
* **Transfer**
* **Vendor**
* **VendorCredit**

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                                                                                   |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Offers free trial or requires paid sandbox?**    | Yes. Intuit provides a free sandbox environment for development and testing. [Create developer account](https://developer.intuit.com/app/developer/qbo/docs/get-started) |
| **Requires partnership to obtain authentication?** | No. However, production apps require app review and approval from Intuit for public distribution.                                                                        |

***

### Authentication (OAuth 2.0)

#### Create your OAuth app (Intuit Developer Portal)

1. Go to **Intuit Developer Portal** (developer.intuit.com) and sign in.
2. Create a new app and select **QuickBooks Online and Payments** as your platform.
3. Configure your app settings:
   * Add the redirect URI: [https://api.alloyautomation.com/oauth/callback](https://api.alloyautomation.com/oauth/callback)
   * Select the scopes you need (typically `com.intuit.quickbooks.accounting`)
4. Note your **Client ID** and **Client Secret** from the Keys & credentials tab.
5. Copy your **Client ID** and **Client Secret** into Alloy Automation.

#### Development vs. Production

* **Development mode:** Limited to 25 connections. Use sandbox company files for testing.
* **Production mode:** Requires app review by Intuit. Submit security questionnaire and app details for approval.

#### Sandbox environment

* Create test company files in the Intuit Developer Portal.
* Use sandbox credentials to test OAuth flow and API calls.
* Data in sandbox companies is isolated from production QuickBooks accounts.

***

## Use Cases

### 1) Automated invoice sync

Sync invoices from QuickBooks to your application in real-time, enabling custom dashboards, analytics, or customer portals without manual data entry.

### 2) Bill payment automation

Automatically create and manage bills and bill payments in QuickBooks based on events in your application—streamlining accounts payable workflows.

### 3) Customer and vendor management

Keep customer and vendor records synchronized between QuickBooks and your CRM or ERP system, ensuring data consistency across platforms.

### 4) Financial reporting & analytics

Extract accounting data (accounts, journal entries, transactions) to build custom financial reports, forecasting models, or compliance dashboards.

### 5) Time tracking integration

Sync time activity data from your time tracking tools into QuickBooks for accurate payroll processing and project billing.

***

## API Gotchas

* ⚠️ **Minor versions:** QuickBooks API uses minor versions that change periodically. Always specify the latest minor version in your requests to avoid deprecated behavior.
* ⚠️ **Rate limiting:** QuickBooks enforces a 500 requests per minute limit per app. Implement exponential backoff for 429 responses.
* ⚠️ **Query limitations:** The query API has limitations on complexity and result set size (max 1000 records per query). Use pagination for large datasets.
* ⚠️ **Sparse updates:** Use sparse=true parameter when updating objects to only modify specified fields and avoid overwriting unchanged data.
* ⚠️ **Webhook verification:** QuickBooks webhooks require payload verification using the Intuit-Signature header to ensure authenticity.
* ⚠️ **Realm ID:** Each QuickBooks company has a unique Realm ID (Company ID) that must be included in all API requests after OAuth.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.