Accounting Integrations

Overview

BlueClerk integrates with QuickBooks, Xero, FreshBooks, and Wave to keep your books in sync automatically. Connect your accounting software once, then invoices, customers, and items sync automatically - no double entry required. BlueClerk monitors sync health and alerts you with notifications when sync failures occur, helping you identify and fix connection issues before they impact your books.

NEW: QuickBooks Batch API for Fast Item Sync - QuickBooks item sync now uses the Batch API to sync 30 items per HTTP request instead of one-at-a-time. With ~500ms per batch over the wire, syncing 3629 items takes ~60 seconds total (121 batches), fitting comfortably in one Vercel function call. This replaces the previous ~20-minute sync that was timing out and returning "Unexpected token 'A'" JSON parse errors. The time budget has been increased to 270 seconds to handle large catalogs in a single run.

NEW: Automatic Batch-Level Fallback - If an entire batch fails (auth error, network issue, or malformed payload), BlueClerk automatically falls back to syncing those 30 items one-at-a-time using the existing create/updateItem methods. This prevents losing 30 successful syncs due to one batch-level error while still achieving massive speed gains on healthy batches.

NEW: One-Click Full Sync - Users can now hit "Sync Now" once on the amber banner showing unsynced items, and all 3629+ items push to QuickBooks in about 60 seconds - no more partial syncs or multiple clicks required for large catalogs.

NEW: Reconnect Required Alert - When QuickBooks refresh tokens expire or are revoked, BlueClerk now shows a friendly "Reconnect Required" message instead of raw "invalid_grant" errors. The client wraps refresh failures in try/catch and re-throws a sentinel error that the syncNow mutation translates to an UNAUTHORIZED tRPC error with instructions: "Your QuickBooks connection has expired. Go to Settings → Integrations → Reconnect QuickBooks."

NEW: Resync Button for Already-Synced Invoices - The sync button now remains visible on SENT invoices even after they've been synced to QuickBooks. When an invoice already has a QuickBooks ID, the button label changes to "Resync to QuickBooks" and pushing it syncs BOTH the invoice data AND any unsynced payments recorded after the initial sync. This fixes the common workflow where you sync an invoice, then record a payment later - the payment now syncs automatically when you click Resync.

NEW: DB-Level Lock for Token Refresh - QuickBooks token refresh now uses a database-level lock to prevent race conditions when multiple serverless functions try to refresh the same token simultaneously. This eliminates the "invalid_grant" errors and security revocations that caused recurring disconnects.

NEW: Idempotent Payment Sync - When you record a payment or mark an invoice paid, BlueClerk now tracks which individual payments have been synced to QuickBooks/Xero/FreshBooks. If you click "Sync to QuickBooks" multiple times or automated syncs retry, duplicate payments are no longer created. Each Payment row gains a quickbooksPaymentId, xeroPaymentId, or freshbooksPaymentId field that's checked before pushing to your accounting provider.

NEW: Payment Sync on Manual Resync - When you click "Sync to QuickBooks" on an invoice, BlueClerk now pushes BOTH the invoice AND any recorded payments in one operation. Previously, the manual sync button only pushed invoice data, leaving payments unsynced even when the invoice showed as paid in BlueClerk. Now, if the invoice has a QuickBooks ID and has payments recorded, the payment sync fires automatically after the invoice sync completes.

NEW: Real Payment Sum Instead of Stale amountPaid - Payment sync now calculates the total payment amount by summing actual payment records (SUM(payments.amount)) instead of reading invoice.amountPaid. This fixes cases where amountPaid was stale (like INV-0047 showing $0 even though a $350 payment existed) due to recalcInvoice misfires or race conditions. QuickBooks always gets the true paid amount now.

Supported Platforms

QuickBooks Online

• Two-way sync - Invoices, customers, and items sync both ways
• Payment recording - Payments recorded in BlueClerk sync to QuickBooks automatically
• Account mapping - Map your items to income accounts
• Automatic token refresh - Connection stays active without manual re-auth
• Batch sync - Sync 30 items per request for fast catalog syncing

Xero

• Two-way sync - Invoices, customers, and items
• Payment recording - Payments sync automatically
• Account mapping - Control which accounts revenue flows into
• Automatic refresh - Token refreshes automatically before expiring

FreshBooks

• Two-way sync - Invoices, customers, and items
• Payment recording - Payments sync automatically
• Automatic refresh - Connection stays active

Wave

• Customer sync - Import customers from Wave
• Invoice sync - Push invoices to Wave automatically
• Limited two-way - Wave API has more restrictions than QB/Xero

Setting Up an Integration

QuickBooks Setup

1. Go to Settings > Integrations
2. Click "Connect QuickBooks"
3. Sign in to QuickBooks when prompted
4. Authorize BlueClerk to access your QuickBooks account
5. Complete post-connection wizard:
   • Import existing customers from QuickBooks
   • Import service items from QuickBooks
   • Map items to income accounts
6. You're connected - invoices and customers sync automatically

Xero Setup

1. Go to Settings > Integrations
2. Click "Connect Xero"
3. Sign in to Xero and authorize BlueClerk
4. Complete post-connection wizard:
   • Import customers
   • Import items
   • Map accounts
5. Start syncing automatically

FreshBooks Setup

1. Go to Settings > Integrations
2. Click "Connect FreshBooks"
3. Authorize BlueClerk
4. Import customers and items
5. Map accounts

What Syncs and When

Automatic Syncing

• Invoices: Sync when marked SENT or PAID
• Customers: Sync when added or updated
• Items: Sync when added or updated in your catalog
• Payments: Sync when recorded on invoices

Manual Syncing

You can manually trigger syncs from:

• Invoice detail page - "Sync to QuickBooks" or "Resync to QuickBooks" button
• Integration settings page - "Sync Now" button
• Account mapping page - Sync selected items or all unmapped items

Account Mapping

Why It Matters

QuickBooks, Xero, and FreshBooks need to know which income account to post revenue to. Account mapping ensures your items sync correctly:

1. Go to Settings > Integrations > Account Mapping
2. Select an income account for each item in your catalog
3. Changes save automatically - no "Save Changes" button needed
4. After saving, BlueClerk automatically syncs your items to your accounting provider

Bulk Operations

• Map Selected - Select items with checkboxes, choose an account, click "Map Selected"
• Map All Unmapped - Applies one account to all items without mappings
• Sync Selected to QuickBooks - Select specific items to sync (capped at 100 per click)

Monitoring Sync Health

Sync Status Alerts

BlueClerk monitors your integration connection and alerts you when issues occur:

• Red alert - Integration disconnected or token expired (shows "Reconnect Required")
• Amber alert - Some items aren't synced yet
• Green status