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.

CRITICAL: Secure Token Handling - OAuth tokens for QuickBooks, Xero, and FreshBooks are encrypted at rest in the database. The system validates credentials during OAuth setup - rejecting empty strings, placeholder values, and unset environment variables immediately to prevent connection failures. When auto-sync encounters authentication errors (invalid tokens, revoked access, or expired credentials), BlueClerk automatically marks your accounting connection as down, clears the stored refresh token, and sends you a notification so you can reconnect.

CRITICAL: Square Payout Sync for QuickBooks - When Square payouts settle (payout.sent event), BlueClerk automatically creates QuickBooks Deposit records that match your net bank deposit. The deposit includes one positive line per payment in the payout (from Undeposited Funds) and one negative line for total processing fees (to Merchant Service Fees expense account), ensuring your QuickBooks balance matches your actual bank deposits for one-click reconciliation. This only happens when you have QuickBooks connected with auto-sync enabled.

CRITICAL: Webhook Security Hardened - Square webhook verification now requires the SQUARE_WEBHOOK_SIGNATURE_KEY environment variable in production. If the key is missing, webhooks are rejected with a 503 error to prevent unauthorized POST requests from marking invoices paid. In development (NODE_ENV != production), webhooks are allowed through without signature verification for local testing. This mirrors the existing QuickBooks webhook security fix.

CRITICAL: Sync Must Be Awaited - Invoice and payment sync operations are now properly awaited in auto-sync flows. Previously, fire-and-forget dynamic imports were terminated by Vercel lambda shutdowns before completion, leaving Payment rows stuck in PENDING state forever. Now, both syncInvoiceToProvider and syncPaymentToProvider are awaited, and failures are logged with structured error details plus in-app notifications for visibility.

NEW: Connection Down Status on Auth Failures - When auto-sync encounters authentication errors (invalid tokens, revoked access, or expired credentials), BlueClerk automatically marks your accounting connection as down and sends you a notification. This helps you quickly identify and fix connection issues before they impact your books. The system creates one notification per auth failure type to avoid alert spam.

NEW: Advisory Lock for QuickBooks Token Refresh - QuickBooks token refresh now uses PostgreSQL advisory locks to prevent race conditions when multiple serverless functions try to refresh the same token simultaneously. The system acquires an exclusive lock before checking token expiration, refreshes the token if needed, then releases the lock - all within a single database transaction. This eliminates the "invalid_grant" errors and security revocations that caused recurring disconnects when parallel requests raced to refresh tokens at the same time.

NEW: Hardened Token Security - OAuth tokens for QuickBooks, Xero, and FreshBooks are now encrypted at rest in the database and validated before use. Empty strings, placeholder values, and unset environment variables are rejected immediately during OAuth setup, preventing connection failures from misconfigured credentials. This eliminates the "tokens suddenly stop working" issue caused by environment variable pollution.

NEW: Email Notification on Sub Ticket Assignment - When you assign a ticket to a subcontractor, both you and the subcontractor receive automatic email notifications. The subcontractor gets an alert that work has been assigned to them, and you receive a confirmation that the assignment was sent successfully. This ensures clear communication and prevents missed work assignments.

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.

Supported Providers

QuickBooks Online

• Invoice sync - Invoices, line items, customers
• Payment sync - Automatically records payments with proper linkage
• Deposit sync - Creates QB Deposit records for Square payouts with fee accounting
• Item sync - Service items and products
• Two-way sync - Pull customers and items from QuickBooks
• Auto-refresh tokens - Stays connected without manual re-auth (with advisory lock protection)

Xero

• Invoice sync - Invoices, line items, contacts
• Payment sync - Payment records with proper references
• Payout fee sync - Creates SPEND bank transactions for Square/Stripe fees
• Item sync - Service items and products
• Two-way sync - Pull contacts and items from Xero

FreshBooks

• Invoice sync - Invoices, line items, clients
• Payment sync - Payment records linked to invoices
• Item sync - Service items
• Two-way sync - Pull clients and items from FreshBooks

Wave

• Invoice sync - Invoices, line items, customers
• One-way sync - BlueClerk → Wave only

Connecting Your Accounting Software

QuickBooks Setup

1. Go to Settings > Integrations
2. Find QuickBooks in the accounting section
3. Click "Connect"
4. Sign in to QuickBooks when prompted
5. Authorize BlueClerk to access your company data
6. Select your company if you have multiple
7. Import customers and items using the post-connection wizard

Xero Setup

1. Go to Settings > Integrations
2. Find Xero in the accounting section
3. Click "Connect"
4. Sign in to Xero when prompted
5. Authorize BlueClerk to access your organization
6. Select your organization if you have multiple
7. Import contacts and items using the post-connection wizard

FreshBooks Setup

1. Go to Settings > Integrations
2. Find FreshBooks in the accounting section
3. Click "Connect"
4. Sign in to FreshBooks when prompted
5. Authorize BlueClerk to access your account
6. Import clients and items using the post-connection wizard

How Sync Works

Automatic Sync

When auto-sync is enabled:

• New invoices sync automatically when marked as SENT (DRAFT and VOID excluded)
• Payments sync automatically when recorded
• Customers sync when created or updated
• Items sync when created or updated
• Square payouts sync to QB Deposits when payout.sent webhook received (QuickBooks only)

Manual Sync

You can also sync manually:

1. Open an invoice that needs syncing
2. Click "Sync to [Provider]" or "Resync to