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.

Important behavior & protections

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

• Email send errors do not block accounting sync — Sending an invoice email is decoupled from the accounting sync workflow: even if an invoice email fails to deliver, BlueClerk will still attempt to sync the invoice and any related payment to your connected provider. Failures in email delivery are handled separately (logged and surfaced to the sender), while sync attempts continue so your books remain up to date.

What to expect in the UI

• Integration status pages show connection health, last synced timestamps, and recent error summaries.
• In the Invoices list and invoice detail page you will see sync status badges such as:
  • "Synced to QuickBooks" (green)
  • "Out of Date" / "Not synced to QuickBooks" (yellow)
  • "Blocked" (red) when the accounting connection is down.
• When auto-sync or manual sync fails, BlueClerk surfaces structured, human-readable error messages explaining the reason and pointing you to the right fix.

Fix Now — repair item mapping errors directly from an invoice

New: when an invoice fails to sync because of an item-level accounting mapping problem (for example, an item’s saved income account no longer exists in QuickBooks), the invoice detail sync UI now offers a Fix Now workflow so you can repair the item without leaving the invoice.

How it works for contractors and admins:

1. On the invoice detail page, click the "Sync to QuickBooks" button (or