This guide explains how Albi integrates with QuickBooks Desktop (QBD), focusing on how project syncing works, how auto-syncing behaves, and what common issues to look out for. If you're a new user, support team member, or just troubleshooting, this will give you the basics you need to work effectively with the QBD integration.
Overview: How Syncing Works
Project Creation & Syncing
Create projects in Albi, not QBD. Albi is the source of truth for project and customer records.
When a project is created in Albi (and the company is QBD-connected), Albi pushes that project to QBD.
If a customer record already exists in QBD (based on name/email/phone), Albi attempts to match it. Otherwise, it creates a new customer.
Edits should be made in Albi, which will update QBD. Do not edit QBD directly to avoid breaking the sync.
If a customer record exists in both Albi and QBD, it's important to ensure that the email and phone number match in both systems. Mismatched data can cause duplicate customer records to be created in QBD.
Auto-Sync Logic
When the Auto-Sync toggle is ON in QBD settings:
Every 5 hours, Albi checks for and adds “Active” projects to the sync queue.
The Web Connector (which you set up during QBD integration) runs every 15 minutes by default, picking up 10 projects per cycle.
What Counts as an “Active” Project?
A project is considered "Active" and eligible for auto-sync if:
It belongs to a company connected to QBD.
It has a QBD Financial CRMID.
It was created within the last year.
It is not deleted or closed.
It meets one of the following financial conditions:
Accrual Revenueis missing or 0.Total Payment Amountis missing or 0.Accrual Revenue ≠ Total Payment Amount.
Note: Because of the batching (10 at a time), large backlogs can result in a delay before syncing completes.
Troubleshooting & Common Sync Issues
Manually Syncing a Project
Go to the project in Albi.
Navigate to the Financial tab, click “Quickbooks Desktop Sync” button.
Run the Web Connector.
⏳ Note: If there are other projects or sync jobs already in the queue, it may take some time for this project to be processed. The sync is handled in the order received.Confirm that a Financial CRMID is present for the customer.
Known Issues & How to Fix
Issue | Cause | Resolution |
Project not syncing | Missing QBD ID (no Financial CRMID) | Try manual sync again or contact Albi support. |
“Inactive parent cannot have active child” | Customer marked inactive in QBD | Reactivate the customer in QBD. |
“Max connection retries exceeded” | Web Connector error / popup unresolved | Close & reopen QBD + Web Connector. Clear all popups. |
Customer name too long | Character limit issue in QBD fields | Shorten the name in Albi. |
Duplicate customer created | Customer records in Albi and QBD do not have matching email and phone | Ensure email and phone match in both systems before syncing. |
Duplicate sub-customer created | Sub-customer was created manually in QBD instead of via Albi sync | Always initiate customer/project creation from Albi to maintain sync integrity. |
Best Practices
Always create and manage records in Albi.
Do not delete or inactivate customer records in QBD unless you're sure they will never be used again.
If a new email or phone number comes in, update the customer record in Albi—this will sync the update to QBD.
Train new staff on this workflow. Skipping setup training is the #1 cause of sync issues.
Understand the Web Connector behavior: Picks up 10 projects per run
FAQs
Q: Should I create or make edits on customer or sub customer record directly in QuickBooks?
Doing so may break the integration so it's not recommended. Always make changes in Albi.
Q: What happens if I mark a customer as inactive in QBD?
Albi won’t be able to sync new projects to that customer. Reactivate them in QBD.
Q: I created a new project, but it’s not syncing. What do I do?
Your syncing queue may have a backlog of projects, so the Web Connector may take some time to catch up. Try manually triggering the sync from the project’s Financial tab. If the project still doesn’t sync after that, reach out to Albi Support for assistance.