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: Automatic Invoice & Estimate Embedding - When you mark an invoice or estimate as SENT or record a payment, BlueClerk automatically embeds that billing document into your company's RAG memory. This helps the AI chat assistant answer questions like "what did we charge for X" or "what's our typical plumbing markup" using your real pricing history instead of guessing. The system is gated by the RAG_BILLING_EMBED_ENABLED=true environment flag (defaults to off) and fires-and-forget on status transitions only, so each record embeds 1-2 times over its lifetime. Voyage embedding cost: ~$0.00002 per record.

NEW: Backfill Script for Historical Data - Run scripts/backfill-billing-embeddings.ts to embed existing invoices and estimates into RAG memory. The script shows token + cost estimates upfront, requires confirmation, and is opt-in to prevent accidental spend. Example: 10K records = $0.20 in Voyage costs.

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.

NEW: QuickBooks Item Sync Recovery - When QuickBooks returns a duplicate-name error during item creation, BlueClerk now automatically looks up the existing item by name and saves that QuickBooks ID to your catalog. This recovers from "orphan-created" items where QuickBooks created the item but the response wasn't persisted, preventing infinite retry loops on the same item.

NEW: Name Sanitization - Item names are now automatically cleaned before sending to QuickBooks - tabs, newlines, and control characters are stripped, and names are trimmed. This prevents silent rejections on items with literal tab characters like "TKO-\t813PB-1500B".

NEW: Upfront Toast on QuickBooks Item Sync - When you click "Sync to QuickBooks" on the integration detail page, a toast immediately fires telling you sync started, it'll take a few minutes for large catalogs, you can navigate away, and to check Sync History when you come back. This prevents users from staring at a spinner or navigating away without knowing if sync finished.

NEW: Reconnect Button on Integration Card - The Reconnect button now appears on the integration card on the main integrations list page, not just on the integration detail page. When your QuickBooks connection needs reconnection, you'll see "Manage", "Reconnect", and "Disconnect" buttons inline on the card - making it faster to restore your connection without navigating to the detail page first.

NEW: QuickBooks Reconnect Button - When your QuickBooks connection expires or is revoked, you'll see an amber "Reconnect Required" banner with a "Reconnect QuickBooks" button. This button takes you directly to the OAuth authorization flow without needing to disconnect and reconnect manually. The banner appears on the integration detail page next to the Disconnect button, making it easy to restore your connection with one click.

NEW: Automatic needsReconnection Detection - When QuickBooks refresh tokens fail during sync (invalid_grant error), BlueClerk automatically clears the refresh token and flips the needsReconnection flag to true. This ensures the amber banner appears immediately after a sync failure, prompting you to reconnect before attempting more syncs.

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.

What Gets Synced

Customers

When you add or edit a customer in BlueClerk:

• Customer details sync to QuickBooks/Xero/FreshBooks - Name, email, phone, address
• Automatically matched - If a customer with the same email exists, they're linked instead of duplicated
• Two-way sync - Import customers from your accounting software to BlueClerk

Items (Services & Products)

Your price book items sync to your accounting software:

• Service items - Labor, repairs, consultations
• Product items - Parts, materials, equipment
• Income account mapping - Each item links to the correct income account for proper revenue categorization
• Cost tracking - Unit costs sync for accurate job profitability

Invoices

When you create or update an invoice in BlueClerk:

• Invoice details sync - Line items, amounts, tax, customer
• Payment status syncs - Marked paid in BlueClerk = paid in accounting software
• Automatic posting - Revenue posts to the correct accounts based on item mappings
• Draft invoices auto-promote - When you save a DRAFT invoice, it changes to SENT so it syncs to your accounting software

Payments

When you record a payment in BlueClerk:

• Payment amount and method sync - Check, cash, credit card, etc.
• Applied to correct invoice - Payments link to the right invoice in your accounting software
• Duplicate prevention - Each payment only syncs once, even if you click sync multiple times
• Batch payment support - Payments applied across multiple invoices sync individually

Connecting Your Accounting Software

QuickBooks Online

1. Go to Settings > Integrations
2. Click "Connect QuickBooks"
3. Sign in to QuickBooks when prompted
4. Authorize BlueClerk to access your Qu