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.

• Email send errors no longer 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. If a sync fails due to authentication or provider errors, the connection is marked down and you'll receive a notification so you can reconnect.

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: Invoice Sync Status Badges - When viewing your integration status page, invoices sent in the last 7 days now show real-time sync badges: green "Synced" when successfully sent to your accounting software, yellow "Out of Date" when local edits haven't synced yet, or red "Blocked" when your accounting connection is down. This helps you quickly identify invoices that need attention before they cause accounting discrepancies.

How It Works

• After you connect your accounting provider, BlueClerk will attempt to sync new and updated customers, items, invoices, and payments automatically.
• Sync operations are retried and failures recorded. Persistent authentication failures cause the integration to be marked "down" so you can re-authorize cleanly.
• Sync runs are awaited so that background processes complete reliably under serverless hosting constraints. This reduces the risk of partial or orphaned records in your accounting system.

Troubleshooting & Notifications

• If you see a "Blocked" badge or receive a connection-down notification, open Settings > Integrations, re-run the authorization flow for the provider, and review the recent sync error details shown on the integration page.
• Email delivery problems (bounces, suppression, or other send failures) are recorded in the document's communications history and surfaced to the sender, but they will no longer prevent invoice or payment records from syncing to your accounting provider.
• For persistent sync errors that are not authentication related, contact support with the sync error details shown on the integration page so we can investigate provider-specific issues.

Best Practices

• Keep OAuth credentials up to date and reconnect providers promptly when notified.
• Review recent invoice sync badges regularly from the Integrations page to catch any "Out of Date" or "Blocked" invoices before month-end reconciliation.
• Use the communications/history tab on invoices to verify email delivery; if delivery failed, resend the email separately—accounting sync will already have been attempted.