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: 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.

NEW: DB-Level Lock for Token Refresh - QuickBooks, Xero, and FreshBooks token refresh now use database-level locks 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.

Supported Providers

QuickBooks Online

• Customer sync - Import customers with full contact details
• Item sync - Sync products and services with income account mapping
• Invoice sync - Create invoices with line items, tax, and payment links
• Payment sync - Record payments when customers pay online or in person
• Automatic token refresh - OAuth tokens refresh automatically every 60 days
• Webhook payment sync - When invoices are paid in QuickBooks, BlueClerk marks them paid automatically

Xero

• Customer sync - Import contacts with billing and shipping addresses
• Item sync - Sync items with tax rates and account codes
• Invoice sync - Create invoices with line items and payment status
• Payment sync - Record payments against invoices
• Automatic token refresh - OAuth tokens refresh automatically
• Bank feed support - Reconcile payments via Xero bank feeds

FreshBooks

• Customer sync - Import clients with contact information
• Item sync - Sync items with pricing and tax configuration
• Invoice sync - Create invoices with line items and payment links
• Payment sync - Record payments when received
• Automatic token refresh - OAuth tokens refresh automatically

Wave

• Customer sync - Import customers with email and address
• Product sync - Sync products and services
• Invoice sync - Create invoices with line items
• Payment tracking - Manual payment recording in Wave

Connecting Your Accounting Software

First-Time Setup

1. Go to Settings > Integrations
2. Find your accounting provider in the list
3. Click "Connect"
4. Sign in to your accounting account when prompted
5. Authorize BlueClerk to access your data
6. Complete the post-connection wizard to import customers and items

Security & Token Management

All OAuth tokens are:

• Encrypted at rest using AES-256-GCM encryption
• Validated before use - empty or placeholder values are rejected
• Automatically refreshed before expiration using database locks
• Never exposed in error messages or logs

If your environment variables are misconfigured (empty strings, missing values, etc.), the OAuth connection will fail immediately with a clear error message during setup - not weeks later when tokens expire.

What Gets Synced

Customers

When you import customers from your accounting software:

• Name and company name
• Email and phone
• Billing and shipping addresses
• Internal accounting IDs for reference

Automatic deduplication - If a customer with the same email already exists in BlueClerk, the import links to that record instead of creating a duplicate.

Items (Products & Services)

Import your service catalog from accounting:

• Item name and description
• SKU or item code
• Unit price
• Income account mapping
• Tax settings

Invoices

When you create invoices in BlueClerk:

• Auto-sync on status change - OPEN and SENT invoices sync automatically
• DRAFT invoices excluded - Stay out of accounting until you mark them sent
• VOID invoices excluded - Won't clutter your books
• Line items with quantities, prices, and descriptions
• Tax calculations
• Payment status updates

Payments

When customers pay invoices:

• Payment amount and date
• Payment method
• Applied to correct invoice
• No duplicates - Tracked by provider payment ID to prevent double-recording

Sync Notifications

When Syncs Fail

If BlueClerk can't sync an invoice, customer, or payment, you'll receive:

• In-app notification with error details
• Email alert (optional, configure in notification settings)
• Dashboard banner showing recent sync failures

Common sync failure causes:

• Token expired (auto-refresh failed)
• Missing required fields (customer email, item account mapping)
• Duplicate records in accounting software
• Network or API timeout

Fixing Sync Issues

1. Check your integration connection - Go to Settings > Integrations
2. Review sync error details in the notification
3. Reconnect if needed - Click "Reconnect" to refresh OAuth tokens
4. Retry the sync - Use "Resync to [Provider]" button on invoices

Token Refresh & Connection Health

Automatic Refresh

OAuth tokens refresh automatically:

• QuickBooks - Every 60 days (expires in 100 days)
• Xero - Every 30 days (expires in 60 days)
• FreshBooks - Every 14 days (expires in 30 days)

Refresh happens in the background when you use the integration. Database locks ensure only one refresh happens at a time, even with multiple serverless functions running.

When Reconnection is Needed

You'll need to reconnect if:

• You revoke access in your accounting software