Account Mapping

Overview

Account mapping ensures your invoice items sync correctly to your accounting software by linking each item to the right income account. When you create an invoice in BlueClerk, the system uses these mappings to post revenue to the correct accounts in QuickBooks, Xero, or FreshBooks automatically.

NEW: Sync Selected Items - You can now select specific items from your catalog and sync just those to QuickBooks instead of all-or-nothing. Filter the items list to what you want (Sync Status: UNSYNCED, Type: PRODUCT, etc.), check the rows, and hit "Sync Selected to QuickBooks" in the bulk actions bar. Pick 50 items, sync in seconds. Pick 100, ~30 seconds. Capped at 100 per click to stay under function timeout limits. This button only appears when you have a QuickBooks integration connected.

NEW: Sync Status Filter - The account mapping table now includes a "Sync Status" filter so you can see at a glance which items are synced, mapped but not synced, or unmapped. This filter only appears when you have an active QuickBooks, Xero, or FreshBooks integration connected.

NEW: Auto-Save on Every Change - Every mapping change now saves immediately to the database and syncs to your accounting provider automatically. When you change a dropdown, click "Map Selected", or click "Map All Unmapped", BlueClerk updates the database instantly with optimistic UI updates and per-row spinners while saving. The "Save Changes" button has been removed - you no longer need a second click to apply your mappings.

NEW: Bulk Actions Auto-Sync - After successfully saving bulk mapping changes ("Map Selected" or "Map All Unmapped"), BlueClerk automatically triggers a full item sync to your connected accounting provider. One click now maps items AND pushes them to QuickBooks/Xero/FreshBooks - no separate "Sync Now" step required.

NEW: Unmapped & Unsynced Alerts - The account mapping page shows two alert banners to help you keep your books in sync:

• Red alert: "N items are unmapped" - appears when items have no income account assigned. Click "Fix Now" to go to account mapping.
• Yellow alert: "N items are mapped but not synced" - appears when items have income accounts but haven't been pushed to your accounting software yet. Click "Sync Now" to push them.

NEW: Guardrails Against QuickBooks Sync Failures - The system now prevents you from creating invoices or estimates with unmapped items when QuickBooks integration is active. If you try to add a line item that doesn't have an income account mapped, you'll see an error message with a link to fix it. This ensures every invoice syncs correctly to QuickBooks without silent failures.

Accessing Account Mapping

1. Go to Settings > Integrations
2. Click your connected provider (QuickBooks, Xero, or FreshBooks)
3. Scroll to "Account Mapping" section or click the "Map Accounts" button

Understanding Income Accounts

What Are Income Accounts?

Income accounts are categories in your accounting software where revenue is recorded. For example:

• Service Revenue - Income from labor/services
• Product Sales - Income from materials sold
• Rental Income - Income from equipment rentals

Why Mapping Matters

When you create an invoice with line items:

• Mapped items → Revenue posts to the correct account in QuickBooks/Xero/FreshBooks
• Unmapped items → Invoice sync fails or revenue goes to a default account
• Wrong mapping → Revenue appears in the wrong place on your P&L

Mapping Items

Individual Item Mapping

1. Find the item you want to map in the account mapping table
2. Click the income account dropdown in the "Income Account" column
3. Select the correct account from your accounting software's chart of accounts
4. The mapping saves automatically with a brief spinner confirmation

Bulk Mapping with Checkboxes

Map multiple items at once:

1. Check the boxes next to items you want to map to the same account
2. Click "Map Selected" in the bulk actions bar that appears
3. Choose the income account from the dropdown
4. Click "Map" in the confirmation dialog
5. All selected items are mapped instantly with optimistic UI updates
6. Items automatically sync to your accounting provider after mapping

Map All Unmapped Items

Apply a default mapping to everything at once:

1. Click "Map All Unmapped" at the top of the table
2. Select the default income account you want to use
3. Click "Map" in the confirmation dialog
4. All unmapped items are mapped to that account instantly
5. Items automatically sync to your accounting provider after mapping

Sync Status Filter

Viewing Sync Status

The sync status filter helps you identify which items need attention:

• Synced - Items successfully pushed to your accounting software
• Mapped - Items with income accounts assigned but not yet synced
• Unmapped - Items without income accounts (will fail to sync)

Using the Filter

1. Click the "Sync Status" dropdown above the table
2. Select a status to filter by (Synced, Mapped, or Unmapped)
3. The table updates to show only items matching that status
4. Clear the filter by selecting "All" to see everything again

Syncing Items to QuickBooks

Sync Selected Items

Push specific items to QuickBooks:

1. Filter items by sync status, type, or search term
2. Check the boxes next to items you want to sync (max 100)
3. Click "Sync Selected to QuickBooks" in the bulk actions bar
4. Wait for sync to complete - progress shows in the UI
5. Sync status updates to "Synced" when done

Sync All Items

Push your entire catalog:

1. Click "Sync All to QuickBooks" at the top of the page
2. Confirm the action in the dialog
3. BlueClerk syncs all mapped items in batches
4. Check sync status after completion

Alerts and Warnings

Unmapped Items Alert

When you have items without income accounts:

• Red alert banner appears at the top of the page
• Shows count of unmapped items
• Click "Fix Now" to filter the table to unmapped items only
• Map them using individual or bulk mapping

Unsynced Items Alert

When you have mapped items that haven't synced yet:

• Yellow alert banner appears below the unmapped alert
• Shows count of items needing sync
• Click "Sync Now" to push all unsynced items to your accounting software
• Banner disappears when all items are synced

Invoice Creation Guardrails

When QuickBooks integration is active:

• You can't add unmapped items to invoices or estimates
• Error message appears with a link to fix the mapping
• This prevents sync failures and ensures clean books

Troubleshooting

Items Not Syncing

If items aren't syncing to your accounting software:

1. Check your integration status - Go to Settings > Integrations
2. Verify connection is active - Reconnect if needed
3. Check sync status filter - Look for items stuck in "Mapped" status
4. Try syncing again - Use "Sync Selected" or "Sync All"
5. Check error logs - Settings > Integrations > [Provider] > Recent Errors

Wrong Income Account

If revenue is posting to the wrong account:

1. Find the item in the account mapping table
2. Change the income account dropdown to the correct account
3. The mapping updates automatically
4. Future invoices will use the new mapping
5. Past invoices remain as-is - edit them in your accounting software if needed

Missing Income Accounts

If an income account doesn't appear in the dropdown:

1. **Go to your