QuickBooks Online: Troubleshooting & FAQ

Setup and Configuration

Why isn't my new project showing up in QBO?

Work through these checks in order:

Check your Customer Condition. Go to Settings → Integrations → QuickBooks → Configure and look at the Customer Condition dropdown. If it's set to Certain Statuses, your project will only sync once it reaches one of the selected statuses. If it's set to Certain Dates, the project syncs only when the chosen date field is filled in. If it's set to Everytime Project Created, projects should sync immediately.
Check the project's QuickBooks ID. Open the project, go to the Basic Info tab, and look for the QuickBooks ID field. If it's blank, the project hasn't synced yet.
Try a manual sync. Open the project, go to the Financials tab, and click the manual Quickbooks Sync button.
Confirm the project meets your sync condition. If you're using Certain Statuses, double-check the project's current status. If you're using Certain Dates, check that the trigger date field is populated.

If the QuickBooks ID still doesn't populate after a manual sync, contact Albi Support.

Can I change my Customer Condition setting after initial setup?

Yes. Go to Settings → Integrations → QuickBooks → Settings and change the Customer Condition dropdown to whichever option you'd like to use going forward. If you choose Certain Statuses, you can select multiple statuses and a project hitting any of them will sync.

This change affects new projects going forward. Projects that have already synced under your previous setting will remain in QBO.

Why isn't Albi syncing to my existing QBO Projects?

QBO has two separate features that sound similar but aren't the same thing: Sub-Customers (nested under a parent Customer) and Projects (a separate QBO feature for project-based job costing). Albi's integration only works with QBO Sub-Customers — it doesn't sync to QBO Projects.

If your existing QBO setup uses Projects rather than Sub-Customers, your Albi projects won't sync to those records. You have two options:

Convert your QBO setup to use Sub-Customers. This is the long-term fix and is required for the integration to work as designed. Each customer relationship in QBO becomes a parent Customer, with each job nested as a Sub-Customer underneath. This can be a significant change depending on how much QBO history you have.
Contact Albi Support. If you have a lot of existing QBO Projects and aren't sure how to restructure them — or you want help doing this without losing financial history — reach out and we'll help you plan the migration.

Can I request a mass sync to bring my historical QBO data into Albi?

Yes — Albi Support can run a mass sync on your behalf. To make sure your request gets handled correctly, please include the following information when you reach out:

Which scenario describes your situation:
- You're a new Albi customer with existing projects in QBO, and you'd like to match your imported Albi projects with their existing QBO sub-customers (and bring in all associated transactions: invoices, payments, expenses, credit memos, etc.).
- You're already connected and want to re-sync transactional records for projects that are currently linked to QBO.
- You're seeing an issue with a specific project or transaction and want it investigated.
Whether you want new sub-customers created in QBO for any Albi projects that don't have a match. By default, mass syncs only match against existing QBO sub-customers — if you want missing ones created automatically, please call this out specifically in your request.
The list of projects (or a way to identify them) if your request is scoped to specific projects rather than your whole company.

Note: Mass syncs only work with QBO Sub-Customers, not QBO Projects. See "Why isn't Albi syncing to my existing QBO Projects?" above if you're unsure which structure your QBO uses.

Can I switch to a new QBO account (for example, for a new fiscal year)?

Yes, you can disconnect your current QBO account and connect a different one — the technical mechanism is the same as any disconnect/reconnect. However, switching QBO accounts has implications for your historical financial data that aren't always obvious, and we strongly recommend reaching out to Albi Support before you make the switch.

A few things to know going in:

When the new QBO account connects and your projects sync, Albi will create fresh customer and sub-customer records in the new QBO. Your existing Albi projects will not pre-populate with the financial history that lived in the old QBO.
Financial records (invoices, payments, expenses) from your old QBO account remain in the old QBO and in Albi — but they won't migrate into the new QBO automatically.
Depending on what you want to preserve and how you want your books to look in the new QBO, the right approach varies.

To make sure the switch goes smoothly, contact Albi Support before disconnecting. We'll walk through what you're trying to accomplish and what data needs to move (or be re-entered) so you don't end up with gaps or surprises.

Day-to-Day Use

Where can I find a project's QuickBooks ID?

There are two places:

The project's Basic Info tab — look for the QuickBooks ID field.
The Integrations button at the top right of the project — opens a popover showing the linked QBO record.

If the QuickBooks ID is blank, the project hasn't synced yet.

Can I create invoices and payments in Albi instead of QBO?

It depends on whether the project has synced to QBO yet:

Before a project syncs to QBO, you can create invoices and payments natively in Albi.
Once a project has synced to QBO, the native invoice and payment creation options are no longer available for that project. From that point forward, all financial records must be created in QBO and will pull into Albi automatically.

Important: Anything you create natively in Albi before a project syncs will not push to QBO when the project does sync. If you need a record to appear in both systems, create it in QBO after the project has synced.

Why don't I see options to create expenses, sales receipts, credit memos, or bank deposits in Albi?

Because your company is connected to QBO, those record types are QBO-only by design. They can only be created in QuickBooks Online and will pull into Albi automatically once they exist in QBO. This applies whether or not a specific project has synced.

How do I link an invoice I created in QBO to the matching Albi project?

You don't need to manually link it. As long as the invoice is associated with the right Sub-Customer (the project name) in QBO, Albi will pull it in automatically and display it on the project's Financials tab.

The most common reason an invoice doesn't appear in Albi is that it was accidentally created against the parent Customer (the customer relationship) instead of the Sub-Customer (the project). In QBO, double-check which name the invoice is filed under:

Open the invoice in QBO.
Confirm the customer field is set to the Sub-Customer (project), not the parent Customer.
If it's wrong, update it in QBO so it's associated with the correct Sub-Customer.
Open the project in Albi, go to the Financials tab, and click the manual sync button.

If the invoice has already had a payment applied to it in QBO and you can't change the customer name as a result, contact Albi Support — we'll help you sort it out.

Can I archive an inactive customer in QBO from inside Albi?

No. Archiving customers in QBO has to be done in QBO directly. Albi doesn't currently have a feature to archive QBO customers from the Albi side.

Why is my closed project showing up as not closed in reports or dashboards?

This is intentional behavior. When a project is closed in Albi and a financial transaction posts to it in QBO afterward — for example, a late payment — Albi keeps the project's Closed status but flips the Closed flag from "Yes" to "No." This way, the new financial activity is captured against the project, but the project's status itself isn't disturbed.

What this looks like in practice:

The project's status still displays as "Closed" (or whatever closed-equivalent status you use).
On dashboards or reports that filter by Closed = Yes, the project will no longer appear — even though its status hasn't changed.
On the Project Status Dashboard these re-opened projects will now appear under the "closed" status column (or the status they were in before they were marked 'close').
The project timeline will include an entry indicating the project was reopened due to a QBO update.

If you want the project to be marked as Closed = Yes again after reviewing the new financial activity, re-close the project from its actions menu at the top right.

Errors and Sync Issues

My QBO connection seems broken — nothing is syncing. What should I check?

When syncing stops working across the board (not just a single project), the most common cause is an expired QBO authentication token. QBO authentication tokens expire periodically, and once expired, Albi can't push or pull data until the connection is refreshed.

The standard fix is to disconnect and reconnect:

Go to Settings → Integrations → QuickBooks.
Open the integration settings and click Disconnect.
Once disconnected, click Connect to re-authorize with QBO. Sign in to QBO with your admin credentials and approve the connection.
Try syncing a project to confirm the connection is working again.

Note: Disconnecting and reconnecting won't delete or unlink any existing synced records. Customer and project links are preserved across the disconnect/reconnect cycle.

If disconnecting and reconnecting doesn't restore syncing, contact Albi Support.

Why is my project failing to sync with a customer-related error?

A few different errors fall into this category — "Customer does not exist," "Customer was created, project was not created," or a generic sync failure — and they usually trace back to one of three causes. Try these in order:

Check for a leftover Financial CRMID on the customer. When a customer record in Albi has an outdated or stale Financial CRMID attached to it, new projects under that customer can fail to sync. To fix this, find the Financial CRMID on the customer's basic info, write it down, then remove it and try syncing the project again. If a new Financial CRMID is generated and the project syncs successfully, the old ID was the problem.
Check for a name conflict in QBO. QBO requires customer names to be unique across all entity types — a name used for a Vendor or an Employee can't also be used for a Customer. If your project's customer name matches an existing Vendor or Employee in QBO, the sync will fail. Update the customer's name in Albi (or the conflicting record's role in QBO) so the names no longer collide, then try syncing again.
Check for special characters in the project name. Project names containing certain special characters may not sync to QBO. If your project name has unique characters in it (such as colons or other punctuation), try editing the project name to remove them and sync again.

If none of these resolve it, contact Albi Support and include the project name, the error message you're seeing, and a note of which steps you've already tried.

What does the QBO error "name supplied already exists" mean?

This error means QBO is rejecting an Albi action because a record with the same name already exists in QBO — typically a customer or sub-customer name conflict. QBO requires unique customer and sub-customer names.

Resolving this safely depends on which side has the correct data, so we recommend reaching out before making any changes:

Take a screenshot of the error message.
Note the project name in Albi.
Contact Albi Support and include both. We'll help you identify the conflict and walk through the cleanup so you don't lose financial records on either side.

Why is an invoice or payment showing twice in Albi when it only appears once in QBO?

Duplicate records in Albi when only one exists in QBO are usually a sign of a sync issue rather than something you can resolve from your end. The most common trigger we've seen is editing an invoice in QBO after it has already synced to Albi — the sync occasionally creates a duplicate instead of updating the existing record.

If you're seeing duplicates:

Confirm in QBO that only one record actually exists for the project.
Note the invoice number, the project name, and the dollar amounts shown on each duplicate in Albi.
Contact Albi Support. Resolving duplicates safely requires removing the extra record on the Albi side, which our team handles directly — please don't try to delete or modify them yourself.

Why doesn't my project's balance in Albi match QBO?

Because Albi only displays what QBO sends, a mismatch usually means either (a) the QBO numbers themselves don't reflect what you expect, or (b) something prevented a record from syncing into Albi. Start your investigation in QBO:

Pull a Profit & Loss report from QBO for the project (Sub-Customer). Compare those numbers to what Albi is showing.
If the QBO numbers also don't match what you expect, the discrepancy lives in QBO — review the project's transactions in QBO directly to find the issue.
If the QBO numbers are correct but Albi is missing records or amounts, work through these checks:
- Were any invoices or payments created natively in Albi before the project synced to QBO? Those records stay in Albi and never push to QBO, so they appear in Albi but not in your QBO balance.
- Are any expenses categorized in QBO under an account subtype that isn't in your Imported Account Subtypes for Expenses list? Those expenses won't sync to Albi.
- Have any QBO records been added recently that may not have synced yet? Try a manual sync from the Albi project Financials tab.

If the numbers still don't reconcile after this, contact Albi Support with the QBO P&L report and a description of what's missing or wrong in Albi.

Why aren't some of my QBO expenses pulling into Albi?

The most common reason is that the expenses' account subtype isn't selected in your Imported Account Subtypes for Expenses list. Only expenses tied to selected account subtypes sync into Albi.

To check:

In QBO, open the expense and note the account it's categorized under, including the account subtype.
In Albi, go to Settings → Integrations → QuickBooks → Settings.
Scroll to Imported Account Subtypes for Expenses and confirm that subtype is in your selected list.
If it's missing, add it and save.

Newly added subtypes will apply going forward. For expenses already created in QBO under a subtype that wasn't previously selected, try editing the expense in QBO, saving it, then manually syncing in Albi. If this doesn't resolve the issue, contact Albi Support.

How do I get a pre-sync invoice from Albi into QBO?

Pre-sync native invoices and payments stay in Albi only — they do not back-fill into QBO once the project syncs. To get the record into QBO, you need to create it directly in QBO against the project's Sub-Customer. The version in QBO will then pull back into Albi alongside the existing native record.

If you'd prefer not to have both records visible in Albi, remove the integration ID by going to the Actions button on the project, select integrations, and unlink from QBO. This will allow you to then delete the native invoice. Once the invoice is delete, you can manually sync the project back to QBO.

Contact Albi Support for help cleaning up the native record after the QBO version has synced.

When to Contact Albi Support

Most QBO integration questions can be resolved using this article and the How to Connect and Configure QuickBooks Online in Albi article. Contact Albi Support if:

A manual sync doesn't resolve a missing project, invoice, payment, or expense.
You're seeing a true duplicate record in Albi (same record, same date, same amount).
A balance mismatch persists after checking pre-sync records, account subtypes, and recent QBO activity.
You receive an error message from QBO that you don't recognize or that this article doesn't cover.
You need help cleaning up data that resulted from a sync issue.

When you contact support, please include:

The Albi project name or ID.
A description of what you expected to happen and what actually happened.
Any error messages you've seen, copied or screenshotted.
The QBO record name or ID, if relevant.