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

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.

Supported Platforms

• QuickBooks Online - Full sync of customers, items, invoices, and payments
• Xero - Full sync of contacts, items, invoices, and payments
• FreshBooks - Full sync of clients, items, invoices, and payments
• Wave - Read-only sync (coming soon)

Connecting Your Accounting Software

QuickBooks Online

1. Go to Settings > Integrations
2. Find "QuickBooks Online" in the list
3. Click "Connect"
4. Sign in to QuickBooks when prompted
5. Authorize BlueClerk to access your QuickBooks account
6. Your connection is active - syncing starts automatically

Xero

1. Go to Settings > Integrations
2. Find "Xero" in the list
3. Click "Connect"
4. Sign in to Xero when prompted
5. Authorize BlueClerk to access your Xero account
6. Select your organization if you have multiple
7. Your connection is active - syncing starts automatically

FreshBooks

1. Go to Settings > Integrations
2. Find "FreshBooks" in the list
3. Click "Connect"
4. Sign in to FreshBooks when prompted
5. Authorize BlueClerk to access your FreshBooks account
6. Your connection is active - syncing starts automatically

What Gets Synced

Customers/Contacts

When you create a customer in BlueClerk:

• Customer record syncs to your accounting software automatically
• Contact info included - name, email, phone, address
• BlueClerk maintains the link so future invoices use the correct customer ID

Items/Products

When you create items in your catalog:

• Items sync as products/services in your accounting software
• Pricing, descriptions, and categories are included
• Account mapping determines which income account each item posts to

Invoices

When you mark an invoice as SENT in BlueClerk:

• Invoice syncs to your accounting software automatically
• Line items post to the income accounts you've configured
• Customer and due date transfer correctly
• DRAFT invoices do NOT sync - only SENT invoices are visible in your books

Payments

When customers pay invoices:

• Payments sync automatically to your accounting software
• Invoice status updates to Paid in both systems
• Payment method and date are recorded
• Applied correctly to the linked invoice

Viewing Sync Status

Integration Status Page

1. Go to Settings > Integrations
2. Click your connected provider (QuickBooks, Xero, or FreshBooks)
3. View sync status:
   • Last sync time
   • Connected by (which user set up the integration)
   • Auto-sync toggle
   • Needs reconnection warning (if refresh token is missing)

Recent Invoice Sync Status

On your integration status page, you'll see a list of invoices sent in the last 7 days with sync badges:

• Green "Synced" - Invoice has been successfully sent to your accounting software and is up to date
• Yellow "Out of Date" - Invoice exists in your accounting software but local edits haven't synced yet
• Red "Blocked" - Sync is blocked because your accounting connection is marked as down
• No badge - Invoice is DRAFT and won't sync until marked SENT

Connection Status

Your integration card shows:

• Green "Connected" - Everything is working normally
• Yellow "Needs Reconnection" - Refresh token is missing, auto-sync will fail soon
• Red "Connection Down" - Authentication failed, auto-sync is blocked until you reconnect

Troubleshooting

Connection Shows "Needs Reconnection"

Problem: Your refresh token is missing - auto-sync will fail on the next attempt.

Solution:

1. Go to Settings > Integrations
2. Click your connected provider
3. Click "Reconnect"
4. Sign in again to your accounting software
5. Authorize BlueClerk when prompted

Invoices Not Syncing

Problem: DRAFT invoices never sync to your accounting software.

Solution:

1. Open the invoice in BlueClerk
2. Click "Mark Sent" in the invoice header
3. The invoice will sync on the next auto-sync cycle (within 5 minutes)

Payments Stuck in PENDING

Problem: Payment records show PENDING status and never sync.

Solution:

1. Check your integration status - is your connection down?
2. Reconnect if needed (see above)
3. Payments will retry automatically on the next sync cycle after reconnection

Invoice Shows "Out of Date"

Problem: You edited an invoice locally but the changes haven't synced yet.

Solution:

1. Wait for auto-sync - changes sync within 5 minutes
2. **Or click "Sync Now"