QuickBooks Desktop Integration
Connect Readybuild to QuickBooks Desktop to synchronize financial data between systems. This integration uses the QuickBooks Web Connector, a bridge application that runs on your computer to exchange data between Readybuild and QuickBooks Desktop.
Overview
The QuickBooks Desktop integration provides two types of synchronization:
- Import (QuickBooks → Readybuild): Brings data from QuickBooks Desktop into Readybuild
- Export (Readybuild → QuickBooks): Sends data from Readybuild to QuickBooks Desktop
Key Features
- Export customers, vendors, and projects from Readybuild to QuickBooks
- Bidirectional bill sync between Readybuild and QuickBooks
- Import customer payments from QuickBooks into Readybuild
- Time entry exports with employee and payroll code mapping
- Estimate and invoice exports with cost code mapping
- Purchase order exports for vendor management
- Queue-based processing for reliable data exchange
- Edit Sequence Management to prevent conflicts when records are modified
- Initial import utility for customers, jobs, and vendors during setup
Prerequisites
Before setting up the integration, ensure you have:
- QuickBooks Desktop Pro, Premier, or Enterprise edition
- QuickBooks Web Connector installed (free download from Intuit)
- Administrator access to QuickBooks Desktop
- Administrator access in Readybuild
- Access to the computer where QuickBooks is installed
Setup Instructions
Step 1: Navigate to Integration Settings
- Go to Settings > Integrations in Readybuild
- Find QuickBooks Desktop in the list
- Click Configure
Step 2: Download and Install the QWC File
The QWC (QuickBooks Web Connector) file tells the Web Connector how to communicate with Readybuild.
- Ensure QuickBooks Desktop is open and you're logged in as an Admin
- Verify the Web Connector is installed on the same computer
- Open the Readybuild QuickBooks Desktop settings page from that computer
- Click Download QWC File
- Open the downloaded QWC file
Step 3: Authorize the Web Service
When you open the QWC file, the Web Connector will launch:
- A window titled Authorize New Web Service appears
- Click OK to authorize
- QuickBooks may prompt you to confirm the connection—click Yes, Always
Step 4: Enter the Access Code
- Copy the Access Code shown in Readybuild
- In the Web Connector, paste it into the Password field for "Readybuild Integration"
- Check the box next to save the password
Step 5: Configure Auto-Sync (Optional)
For automatic synchronization:
- In the Web Connector, check the box next to "Readybuild Integration"
- Set the Every_Min value (e.g., 30 for every 30 minutes)
- Click Auto-Run to enable automatic syncing
Step 6: Run Initial Sync
- Check the box next to "Readybuild Integration"
- Click Update Selected
- Wait for the sync to complete
Configuration Tabs
Employee Mapping
Map Readybuild users to QuickBooks employees for accurate time entry exports.
- Click the Employee Mapping tab
- For each Readybuild user, select the corresponding QuickBooks employee
- Click Save to store the mappings
To refresh employee data from QuickBooks:
- Click the Refresh button
- Wait for the next Web Connector sync
- New employees will appear in the dropdown
Payroll Code Mapping
Link Readybuild pay types to QuickBooks payroll items.
- Click the Payroll Code Mapping tab
- For each pay type (Regular, Overtime, etc.), select:
- Default Payroll Item: The QuickBooks payroll item to use by default
- Category-specific overrides: Different payroll items for specific cost categories
- Click Save to apply
Common Pay Types:
- Regular Time
- Overtime
- Double Time
- PTO/Vacation
Cost Code Mapping
Connect Readybuild cost categories to QuickBooks service items.
- Click the Cost Code Mapping tab
- Set default mappings for:
- Material Items: For material cost codes
- Labor Items: For labor cost codes
- Subcontractor Items: For sub cost codes
- Allowance Items: For allowance cost codes
- Optionally set category-specific overrides
- Click Save
How Sync Works
Queue-Based Processing
The QuickBooks Desktop integration uses a queue system:
- Readybuild queues items to send to QuickBooks
- Web Connector connects and processes the queue
- Results are sent back to Readybuild
- Queue items are marked complete or retried on error
Integrated Entities
The following table shows all data types synchronized between Readybuild and QuickBooks Desktop:
| Entity | Sync Direction | Fields Synchronized |
|---|---|---|
| Customers | Export (Readybuild → QB) | Name, Company Name, First/Last Name, Billing Address, Phone, Alt Phone, Fax, Email, CC Email |
| Vendors | Export (Readybuild → QB) | Company Name, First/Last Name, Vendor Address, Phone, Alt Phone, Fax, Email, CC Email, Name on Check |
| Jobs (Projects) | Export (Readybuild → QB) | Job Name/Title (Project ID + Title), Parent Customer, Job Site Address, Job Status, Start Date, Projected End Date, End Date, Description |
| Estimates | Export (Readybuild → QB) | Customer/Project Reference, Reference Number, Memo (Name), Line Items with Cost/Markup by Cost Code |
| Customer Invoices | Export (Readybuild → QB) | Customer Reference, Transaction Date, Invoice Number, Line Items (Description, Quantity, Rate, Cost Code) |
| Bills | Bidirectional | Vendor Reference, Transaction Date, Due Date, Reference Number (Vendor Bill Number), Memo/Title, Line Items (Description, Quantity, Cost, Amount, Cost Code, Project Reference) |
| Customer Payments | Import (QB → Readybuild) | Payment Amount, Transaction Date, Reference Number, Payment Method, Applied-to Invoice References |
| Credit Memos | Export (Readybuild → QB) | Customer/Project Reference, Transaction Date, Reference Number, Memo, Line Items (Description, Quantity, Rate, Amount, Cost Code) |
| Purchase Orders | Export (Readybuild → QB) | Vendor Reference, Ship-to Reference (Project), Transaction Date, PO Number, Ship Address, Expected Date, Vendor Message, Line Items (Description, Quantity, Rate, Amount, Manufacturer Part Number) |
| Time Tracking | Export (Readybuild → QB) | Transaction Date, Employee Reference, Customer/Project Reference, Service Item Reference, Duration, Payroll Item, Notes, Billable Status |
| Employees | Import (QB → Readybuild) | Employee list for mapping to Readybuild users |
| Payroll Items | Import (QB → Readybuild) | Payroll wage items for pay type mapping |
| Service Items | Import (QB → Readybuild) | Service items for cost code mapping |
| Sales Tax Items | Import (QB → Readybuild) | Sales tax items for tax configuration |
Initial Import Capabilities
During initial setup, the integration can import existing data from QuickBooks:
- Customers: Import your customer list to create contacts in Readybuild
- Jobs: Import jobs linked to customers as projects in Readybuild
- Vendors: Import vendor list to create vendor contacts in Readybuild
This is a one-time import to help with initial onboarding. Ongoing changes to customers, vendors, or projects in QuickBooks are not automatically synced back to Readybuild.
You can also download existing customer/job data to a CSV file if QuickBooks data needs to be merged with other datasets and imported via CSV.
Sync Direction Summary
| Data Type | Direction | Description |
|---|---|---|
| Employees | QuickBooks → Readybuild | Import employee list for mapping |
| Payroll Items | QuickBooks → Readybuild | Import payroll items for mapping |
| Service Items | QuickBooks → Readybuild | Import service items for cost codes |
| Time Entries | Readybuild → QuickBooks | Export approved time entries |
| Bills | Bidirectional | Bills sync both ways between systems |
| Customer Payments | QuickBooks → Readybuild | Import customer payments |
| Invoices & Estimates | Readybuild → QuickBooks | Export invoices and estimates |
Sync Frequency
- Manual: Click "Update Selected" in Web Connector
- Automatic: Configure Every_Min setting (recommended: 30-60 minutes)
- On-demand: Use the Refresh button in Readybuild for specific data
Queue Management
Monitor sync status from the QuickBooks Desktop Queue page:
- Go to Settings > Integrations
- Click Queue next to QuickBooks Desktop
Queue Status Indicators
| Status | Meaning |
|---|---|
| Queued | Waiting for Web Connector |
| In Progress | Currently being processed |
| Complete | Successfully processed |
| Error | Failed—check error message |
Error Handling
The integration includes automatic error handling for common sync issues:
Edit Sequence Mismatch (Error 3200)
What it means: The record was modified in QuickBooks after Readybuild queued the sync.
How it's handled: The system automatically fetches the latest Edit Sequence from QuickBooks and retries the operation.
Reference Not Found (Error 3180)
What it means: A referenced entity (like a customer or vendor) doesn't exist in QuickBooks.
How it's handled: The system logs the error with full details and removes the item from the sync queue to prevent repeated failures. Review the log to identify missing references.
Common Resolution Steps
- Check the sync log for the specific error message
- Verify the referenced entity exists in QuickBooks
- Re-sync the parent entity first (e.g., sync customer before invoice)
- For persistent errors, check QuickBooks for any prompts or dialogs
Troubleshooting
Web Connector Not Syncing
Problem: Data isn't syncing between systems
Solution:
- Verify Web Connector is running (check system tray)
- Ensure QuickBooks is open and logged in
- Check that "Readybuild Integration" is checked in Web Connector
- Verify the password (Access Code) is correct
- Click Update Selected to force a sync
"Application Not Found" Error
Problem: Web Connector can't find QuickBooks
Solution:
- Open QuickBooks Desktop and log into your company file
- Close and reopen Web Connector
- Try syncing again
Access Code Changed
Problem: Sync fails after system update
Solution:
- Go to Settings > Integrations > QuickBooks Desktop in Readybuild
- Copy the current Access Code
- Update the password in Web Connector
Queue Items Stuck
Problem: Items remain in "Queued" status
Solution:
- Verify Web Connector is running
- Check that auto-run is enabled or manually click Update Selected
- Review QuickBooks for any prompts or dialogs blocking the sync
Employees Not Appearing
Problem: New employees don't show in mapping dropdown
Solution:
- Click the Refresh button on the Employee Mapping tab
- Run a Web Connector sync
- Wait 1-2 minutes and refresh the page
Best Practices
Initial Setup
- Map all employees first before exporting time entries
- Set default payroll items even if using category overrides
- Test with a small batch before running full exports
Ongoing Maintenance
- Run the Web Connector on a computer that stays on during business hours
- Set auto-run to sync at least once per hour
- Review the queue periodically for errors
- Update employee mappings when new hires are added
Performance Tips
- Keep QuickBooks running during sync windows
- Avoid editing the same records in both systems simultaneously
- Process large exports during off-peak hours
Disconnecting the Integration
To disconnect QuickBooks Desktop:
- Open the Web Connector
- Select "Readybuild Integration"
- Click Remove
- Confirm the removal
Note: Removing the connection from Web Connector does not delete any previously synced data.
Benefits
The QuickBooks Desktop integration provides:
- Reduced Data Entry: Eliminates duplicate data entry between systems
- Real-Time Visibility: Changes sync automatically when Web Connector runs
- Error Recovery: Automatic handling of common sync conflicts
- Job Costing: Maintains connections between projects, invoices, bills, and payments for accurate job profitability tracking
Frequently Asked Questions
Q: Can I use QuickBooks Desktop and QuickBooks Online at the same time?
A: No, only one QuickBooks integration can be active. Choose the version that matches your accounting software.
Q: Does the Web Connector need to run all the time?
A: We recommend keeping the Web Connector running continuously during business hours and setting the auto-run interval to the shortest setting possible for the best experience.
Q: What happens if QuickBooks is closed during a sync?
A: The Web Connector will fail and retry on the next scheduled sync. No data is lost.
Q: How do I sync time entries to QuickBooks?
A: Time entries are exported when they're approved in Readybuild. The export uses the employee and payroll mappings you've configured.
Q: Can I map one Readybuild user to multiple QuickBooks employees?
A: No, each Readybuild user maps to one QuickBooks employee. Use separate Readybuild accounts for employees who need distinct QuickBooks mappings.
Q: How do customer payments sync from QuickBooks?
A: Payments recorded in QuickBooks are imported into Readybuild automatically. The system matches payments to invoices using the QuickBooks transaction ID and applies them accordingly.
Q: How do bills sync between systems?
A: Bills are bidirectional. Bills created in Readybuild export to QuickBooks, and bills created in QuickBooks import to Readybuild. The bill is matched to a project based on the Job/Customer reference in the line items.
Q: If I update a customer in QuickBooks, does it update in Readybuild?
A: No. Customer, vendor, and project data flows from Readybuild to QuickBooks only. Changes made in QuickBooks are not automatically synced back. Bills and payments are the exception—those do import from QuickBooks into Readybuild.
Q: How are large datasets handled?
A: The integration uses QuickBooks' iterator functionality to process records in batches (typically 100 at a time), preventing timeouts and memory issues.
Q: Can I sync purchase orders to QuickBooks?
A: Yes, purchase orders created in Readybuild are exported to QuickBooks with full line item details, vendor references, and project associations.
Q: How does job costing work with the integration?
A: Projects in Readybuild are synced as Jobs in QuickBooks, linked to their parent customer. All related transactions (invoices, bills, payments) maintain these project references for accurate job profitability reporting.