Overview
This guide explains how to connect Custodia with QuickBooks Online (QBO) and export expense data to your accounting system.
Prerequisites
Before you begin, confirm the following requirements are met:
- A Custodia account with a Finance or Admin role.
- An active QuickBooks Online subscription (Plus, Advanced, or Essentials).
- Your Chart of Accounts is configured in QBO with account numbers enabled.
- GL (General Ledger) accounts exist in Custodia and match the account numbers in QBO.
The QuickBooks authorization flow opens in a new browser tab.
Setting Up the Integration
Step 1: Navigate to QuickBooks Setup
From the Custodia dashboard, go to:
Finance & Accounting → Accounting Setup → QuickBooks Setup
Step 2: Connect to QuickBooks Online
- Click Connect to QuickBooks at the bottom of the page.
- A confirmation message will appear stating: “You will now continue the process in QuickBooks.”
- Click to QuickBooks to proceed.
- A new browser tab will open and redirect you to the Intuit authorization page.
- Sign in with your QuickBooks Online credentials.
- Select the QuickBooks company you want to connect.
- Click Connect.
Once authorization is completed, you will automatically be redirected back to Custodia and the connection will be saved.
Note: Each QuickBooks connection uses an authorization token with an expiration date. Custodia automatically refreshes these tokens in the background. Reconnection is only required if the token expires or is revoked.
Step 3: Configure the Connection Scope
After connecting, a new row will appear in the QuickBooks Setup grid. Configure the following fields:
| Field | Description |
|---|---|
| Name | A friendly name for the connection (example: US Operations QBO). |
| Scope | Choose ”*” for all subsidiaries or Subsidiary to restrict the connection to one subsidiary. |
| Used For | If Scope is set to Subsidiary, select which subsidiary this connection applies to. |
| Custodia Vendor | The vendor name in QBO under which Custodia transactions will be posted. Defaults to Custodia if not configured. |
Click the row to edit the values and save your changes.
Step 4: Verify the Connection
Click Check Settings to validate the configuration.
This process will:
- Synchronize the QuickBooks Chart of Accounts with Custodia
- Identify unmatched GL accounts
- Synchronize vendor records between Custodia and QBO
If the validation completes successfully, you will see a “No issues found” message. If issues are detected, the system will display a summary so they can be resolved.
Account and Vendor Mapping
GL Account Mapping
Custodia maps expenses to QuickBooks using GL account codes.
For successful exports:
- Ensure account numbers are enabled in QuickBooks.
- Confirm that GL account codes in Custodia match the account numbers in QBO exactly.
- Run Check Settings to synchronize accounts.
During synchronization:
New QBO accounts are automatically imported into Custodia. Updates to existing accounts are refreshed.
Important: Accounts in QuickBooks without an account number will not be imported.
Credit Card Account Mapping
When exporting as Purchases, Custodia automatically creates credit card accounts in QuickBooks using the cardholder name and last four digits of the card.
Example:
Jane Smith 4532These accounts are created as Credit Card type accounts in QBO.
No manual configuration is required.
Vendor Mapping
By default, Custodia exports transactions using a vendor named Custodia.
You can change the vendor if needed:
- Click the Custodia Vendor field in the QuickBooks setup grid.
- Search for an existing vendor from your QBO vendor list.
- Select the vendor and save.
When exporting transactions grouped by employee, Custodia automatically creates vendors in QBO using employee names if they do not already exist.
Exporting Transactions
Starting an Export
- Navigate to Expenses in Custodia.
- Apply any filters you need (date range, subsidiary, status, etc.).
- Click Export to QuickBooks.
- Configure the export settings.
- Click Export to begin the process.
| Option | Description |
|---|---|
| Group Expenses By | Determines how transactions are grouped in QBO: Expense, Activity, Employee, or Subsidiary. |
| Export Reviewed Only | When enabled, only expenses marked Reviewed and Approved will be exported. |
What Happens During Export
When an export begins:
- Custodia creates a background export job.
- Positive transactions are exported as Purchases or Bills depending on configuration.
- Negative transactions (refunds or credits) are exported as Vendor Credits.
- Receipts attached to expenses are uploaded to the QuickBooks transaction.
- Exported expenses are locked in Custodia to prevent modifications.
Export Types
| Type | Description | Best For |
|---|---|---|
| Purchase | Creates Purchase records linked to a credit card account. | Credit card expense tracking |
| Bill | Creates Bill records for payable transactions. | Accounts payable workflows |
Grouping Options
| Grouping | Behavior |
|---|---|
| Expense | Each Custodia expense becomes one QuickBooks transaction. |
| Employee | All expenses for the same employee are grouped into one transaction with multiple line items. |
| Subsidiary | Expenses are grouped by subsidiary. |
| Activity | Expenses are grouped by activity or project. |
Managing the Integration
Multiple Connections
Organizations with multiple subsidiaries can configure multiple QuickBooks connections.
Options include:
- One connection per subsidiary
- One shared connection for all subsidiaries
Use the Scope setting to define this behavior.
Editing a Connection
Click a row in the QuickBooks Setup grid to edit:
- Connection name
- Scope
- Subsidiary assignment
- Vendor mapping
Changes apply immediately to future exports.
Removing a Connection
You can delete a connection directly from the setup grid.
Deleting a connection does not affect previously exported transactions in QuickBooks.
Re-Synchronizing Accounts
Run Check Settings whenever you:
- Add new accounts in QuickBooks
- Rename or deactivate accounts
- Add vendors in QuickBooks
This ensures Custodia remains synchronized with your accounting system.
Troubleshooting
Connection Issues
| Issue | Cause | Resolution |
|---|---|---|
| Could not open QuickBooks | Pop-up blocker is preventing the authorization window from opening | Disable pop-up blockers and try again |
| No QuickBooks connection configured | Integration has not been set up | Click Connect to QuickBooks |
| Connection indicator is red | Authorization token expired or connection incomplete | Delete and reconnect the integration |
| QuickBooks not connected for this company | No valid connection exists for the subsidiary | Configure a connection with the correct scope |
| Token expired | Authorization flow timed out | Restart the connection process |
Export Issues
| Issue | Cause | Resolution |
|---|---|---|
| Some expenses have no GL account | Expense is missing a GL mapping | Assign the GL account before exporting |
| GL accounts not defined in accounting system | Custodia GL accounts do not exist in QBO | Create the account in QBO or update the mapping |
| Expense already exported | Expense was previously exported | Void the transaction in QBO if re-export is required |
| Export job failed | Data or API error | Review the Job Tracker for details |
| Unable to find GL account | Account numbers do not match between systems | Verify account numbers and run Check Settings |
Account Mapping Issues
| Issue | Cause | Resolution |
|---|---|---|
| Unmatched accounts reported | Custodia accounts do not exist in QBO | Create accounts in QBO with matching numbers |
| Accounts missing from import | QBO accounts do not have account numbers | Enable account numbers and assign them |
| Inactive accounts | Account has been deactivated in QBO | Reactivate or update the GL mapping |
Vendor Mapping Issues
| Issue | Cause | Resolution |
|---|---|---|
| Vendor not found | Vendor does not exist in QBO | Create the vendor or use the default Custodia vendor |
| Multiple vendors matched | Duplicate vendor names exist in QBO | Ensure vendor display names are unique |
FAQ
How often does the QuickBooks connection need to be renewed?
Custodia automatically refreshes authorization tokens. However, QuickBooks may require reauthorization if the connection remains unused for an extended period (usually around 100 days).
Can multiple QuickBooks companies be connected?
Yes. Each QuickBooks company can be configured as a separate connection and assigned to specific subsidiaries.
Can an export be undone?
No. Exported transactions are locked in Custodia. If corrections are needed, the transaction must be reversed directly in QuickBooks.
Are receipts exported to QuickBooks?
Yes. Receipts attached to expenses are uploaded as attachments on the QuickBooks transaction.
How are refunds handled?
Negative amounts are automatically exported as Vendor Credits.
Who can configure the QuickBooks integration?
Users with Finance, Auditor, or Support roles can view the integration. Only Finance users can configure or manage the connection.
Are exports real-time?
No. Exports are triggered manually and run as background jobs. Progress can be monitored in the Job Tracker.
Need Help?
Visit our Help Center at support.custodia.ai or contact your Customer Success Manager for directed assistance with your QBO integration.