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: QuickBooks Sales Tax Code Discovery - When you connect QuickBooks, BlueClerk now automatically detects which sales tax codes are available for use on invoices. The system checks your QuickBooks settings to see if sales tax is enabled, then fetches all tax codes and filters out non-usable ones (like adjustment codes or inactive codes). You can see available tax codes in your QuickBooks integration settings and select the one you want to use for taxable invoices.

Connecting Your Accounting Software

QuickBooks

1. Go to Settings > Integrations
2. Find QuickBooks in the list
3. Click "Connect"
4. Sign in to QuickBooks when prompted
5. Authorize BlueClerk to access your data
6. You're connected - BlueClerk will now sync automatically

QuickBooks Sales Tax Setup

After connecting QuickBooks, BlueClerk checks your sales tax configuration:

• If sales tax is enabled in QuickBooks, BlueClerk shows available tax codes in integration settings
• Select your default tax code to use on taxable invoices
• Non-usable tax codes are filtered - adjustment codes, non-tax codes, and inactive codes won't appear
• Without a tax code selected, taxable invoices won't sync to QuickBooks until you choose one

Xero

1. Go to Settings > Integrations
2. Find Xero in the list
3. Click "Connect"
4. Sign in to Xero when prompted
5. Select your organization
6. Authorize BlueClerk
7. You're connected

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
6. You're connected

Wave

Wave integration is coming soon - email support@blueclerk.com if you need it now.

What Gets Synced

Invoices

When you create or update an invoice in BlueClerk:

• Invoice is sent to your accounting software automatically
• Line items are mapped to your chart of accounts
• Customer is linked (or created if new)
• Payments are recorded when received

Customers

• New customers in BlueClerk → created in accounting software
• Existing customers → linked by email or name match
• Customer updates → synced when invoice is created or updated

Items (Products/Services)

• Your catalog items can be synced to your accounting software
• Accounting items can be imported to your BlueClerk catalog
• Prices and descriptions stay in sync

Auto-Sync vs Manual Sync

Auto-Sync (Recommended)

When auto-sync is enabled:

• Every invoice syncs when created or updated
• Payments sync automatically when recorded
• No manual work - just use BlueClerk normally

Manual Sync

If you prefer control:

• Review invoices before they sync
• Click "Sync to QuickBooks" (or Xero/FreshBooks) when ready
• Useful for complex setups or when you want to review first

Troubleshooting Sync Issues

Connection Down Notifications

If BlueClerk can't sync due to authentication errors:

• You'll receive a notification in-app
• Connection status shows "Down" in integration settings
• Reconnect your account to restore sync
• Check that you haven't revoked BlueClerk's access in your accounting software

Syncing Problems

If an invoice won't sync:

• Check connection status in Settings > Integrations
• Verify all line items have items from your catalog (required for accounting sync)
• Review sync error messages in the invoice detail page
• Try manual sync if auto-sync fails

Item Mapping Issues

If items aren't syncing correctly:

• Go to Settings > Account Mapping
• Map each item to the correct income account
• Save changes and try syncing again

Best Practices

Keep Items Mapped

• Map every catalog item to an income account in Settings > Account Mapping
• Unmapped items can't sync and will cause invoice sync failures
• Review mappings when adding new items

Monitor Sync Health

• Check notifications for sync failures
• Review connection status periodically in Settings > Integrations
• Reconnect promptly if your connection goes down

QuickBooks Sales Tax

• Select a tax code in integration settings before creating taxable invoices
• Without a tax code, taxable invoices won't sync to QuickBooks
• Tax codes are pulled from your QuickBooks settings automatically

Security & Privacy

• OAuth tokens encrypted - All access tokens are encrypted at rest in the database
• No password storage - BlueClerk never sees your accounting software password
• Revocable access - You can disconnect anytime from Settings > Integrations
• Validated credentials - Invalid tokens are rejected immediately during setup

Questions

Q: Do I need to enter data twice? A: No - create an invoice in BlueClerk and it syncs automatically to your accounting software.

Q: What happens if sync fails? A: You'll receive a notification with details. Fix the issue (reconnect, map items, etc.) and try again.

Q: Can I disconnect my accounting software? A: Yes - go to Settings >