Sync Reference
This page provides complete documentation of what data syncs between Readybuild and QuickBooks Online, including field mappings, sync directions, and requirements.
Sync Direction Summary
| Entity Type | Direction | Trigger |
|---|---|---|
| Contacts → Customers | Two-way | Automatic |
| Projects → Jobs | Two-way | Automatic |
| Vendors | Two-way | Automatic |
| Estimates | Export only | When marked as sold |
| Time Entries → Time Activities | Export only | Manual from time approval |
| Bills | Two-way | Automatic |
| Bill Payments | Two-way | Automatic |
| Field Receipts → Purchases | Two-way | When approved/paid |
| Client Invoices | Two-way (Doc Number export only) | When flagged for accounting |
| Client Payments | Two-way | When flagged for accounting |
| Credit Memos | Two-way (Doc Number export only) | When flagged for accounting |
How Sync Works
Automatic Sync
Once connected, synchronization happens automatically:
- Real-time: Changes push to QuickBooks when records are saved in Readybuild
- Webhooks: QuickBooks notifies Readybuild of changes made in QuickBooks
- Catch-up sync: Runs periodically to ensure no changes are missed
Sync is triggered by afterInsert and afterUpdate events on models, meaning changes sync immediately when records are created or modified.
Webhook Support
QuickBooks Online sends webhook notifications to Readybuild for the following entity types:
- Customer
- Vendor
- Bill
- Invoice
- CreditMemo
- BillPayment
- Payment
When a webhook is received, Readybuild pulls the latest data from QuickBooks to keep records synchronized.
Sync Status
Each linked entity shows its sync status:
| Status | Indicator | Description |
|---|---|---|
| Pending | Gray clock | Queued for next sync cycle |
| Synced | Green checkmark | Successfully synchronized |
| Error | Red warning | Issue occurred during sync (hover for details) |
| Skipped | Gray dash | Record not eligible for sync |
Customer Data (Contacts → Customers)
| Readybuild Field | QuickBooks Field | Direction |
|---|---|---|
| First Name | Given Name | Two-way |
| Last Name | Family Name | Two-way |
| Company Name | Company Name | Two-way |
| Primary Email Address | Two-way | |
| Phone Numbers | Primary Phone, Mobile, Fax, Alternate Phone | Two-way |
| Website | Web Address | Two-way |
| Address | Billing Address, Shipping Address | Two-way |
| Notes | Notes | Two-way |
| Active Status | Active | Two-way |
Project Data (Projects → Jobs)
Projects sync as "Jobs" in QuickBooks (Customers with Job=true). Each project must have a linked contact that is also synced to QuickBooks.
| Readybuild Field | QuickBooks Field | Direction |
|---|---|---|
| Project ID + Title | Display Name | Two-way |
| Project Address | Ship Address | Two-way |
| Contact Address | Bill Address | Two-way |
| Contact | Parent Customer (ParentRef) | Two-way |
| Description | Notes | Two-way |
Vendors
| Readybuild Field | QuickBooks Field | Direction |
|---|---|---|
| First Name | Given Name | Two-way |
| Last Name | Family Name | Two-way |
| Company Name | Company Name / Display Name | Two-way |
| Phone Numbers | Primary Phone, Mobile, Fax, Alternate Phone | Two-way |
| Website | Web Address | Two-way |
| Address | Billing Address | Two-way |
| Notes | Notes | Two-way |
| Active Status | Active | Two-way |
Estimate Data
Estimates sync one-way from Readybuild to QuickBooks when marked as sold.
| Readybuild Field | QuickBooks Field |
|---|---|
| Estimate ID | Doc Number (prefixed as EST{id}) |
| Estimate Name | Private Note |
| Created Date | Transaction Date |
| Project | Customer Reference |
| Line Items (grouped by cost code) | Line Items |
Payroll Hours (Time Entries → Time Activities)
Time entries sync one-way from Readybuild to QuickBooks via manual action from the time approval interface.
| Readybuild Field | QuickBooks Field |
|---|---|
| Date | Transaction Date |
| Hours | Hours + Minutes |
| Note | Description |
| Employee | Employee Reference |
| Project | Customer Reference |
| Cost Code | Item Reference |
| Billable Status | Billable Status |
Requirements:
- Time entries must be locked (approved) before syncing
- Each employee must have their QuickBooks Online Employee ID configured in team member settings
- Sync is triggered manually from the time approval UI by selecting a date range
Bills
| Readybuild Field | QuickBooks Field | Direction |
|---|---|---|
| Bill Number | Doc Number | Two-way |
| Vendor | Vendor Reference | Two-way |
| Due Date | Due Date | Two-way |
| Invoice Date | Transaction Date | Two-way |
| Title | Private Note | Two-way |
| Line Items | Line Items | Two-way |
| Project | Customer Reference (per line) | Two-way |
| Status (Paid) | Balance = 0 | Two-way |
Bill Payments
Bill payments sync as individual records between Readybuild and QuickBooks:
| Readybuild Field | QuickBooks Field | Direction |
|---|---|---|
| Amount | Amount | Two-way |
| Payment Method | PayType | Two-way |
| Date | Transaction Date | Two-way |
| Payment Account | BankAccountRef / CCAccountRef | Two-way |
| Bill | VendorRef + Line (BillRef) | Two-way |
Multi-bill payments: A single QuickBooks BillPayment that spans multiple bills is imported as separate payment records in Readybuild — one per bill, each with the correct per-bill amount.
Origin tracking: Payments imported from QuickBooks are marked as QBO-originated and are read-only in Readybuild. Edit or delete these payments in QuickBooks; changes sync back automatically.
Delete propagation: When a payment is deleted in Readybuild, the corresponding BillPayment is also deleted from QuickBooks. When a BillPayment is deleted in QuickBooks, the corresponding payment records are removed from Readybuild via webhook.
Bill Actions
Bills support several actions that sync to QuickBooks:
| Action | QuickBooks Behavior | Restrictions |
|---|---|---|
| Void | Configurable (see below) | Cannot void if Checkbook.io payment is active |
| Delete | Deletes bill and payments from QB | Cannot delete Paid or Void bills |
| Duplicate | Creates new draft bill (no QB sync) | None |
Voiding Bills
When you void a bill in Readybuild, the sync behavior depends on your company settings:
| Setting | QuickBooks Behavior |
|---|---|
| Delete (default) | Bill and all associated bill payments are deleted from QuickBooks |
| Add Note | Bill remains in QuickBooks with "(VOIDED in ReadyBuild)" appended to the Private Note |
| None | No action taken in QuickBooks |
Void Reason: When voiding a bill, you can optionally provide a reason. This is stored in Readybuild and included in audit logs.
Restrictions:
- Bills with an active Checkbook.io payment cannot be voided
- Bills already in Void status cannot be voided again
Deleting Bills
When you delete a bill in Readybuild:
- The bill is permanently removed from Readybuild
- If synced to QuickBooks, the bill and any associated bill payments are automatically deleted from QuickBooks
Restrictions: Only bills with status Draft, Billed, or Ready to Pay can be deleted. Bills with status Paid or Void cannot be deleted.
Field Receipts (Field Expenses → Purchases)
Field expenses sync as Purchase transactions in QuickBooks.
| Readybuild Field | QuickBooks Field | Direction |
|---|---|---|
| Purchase Date | Transaction Date | Two-way |
| Title | Private Note | Two-way |
| Vendor | Entity Reference | Two-way |
| Project | Customer Reference | Two-way |
| Line Items | Line Items (Account-based) | Two-way |
| Payment Account | Account Reference | Two-way |
Requirements:
- Field expense must be in Approved or Paid status to sync to QuickBooks
- Vendor must be synced to QuickBooks first
- Cost codes must have QuickBooks account mappings configured
Client Invoices
| Readybuild Field | QuickBooks Field | Direction |
|---|---|---|
| Invoice Number | Doc Number (prefixed as INV{number}) | Export only |
| Due Date | Due Date | Two-way |
| Created Date | Transaction Date | Two-way |
| Title | Private Note | Two-way |
| Project | Customer Reference | Two-way |
| Line Items | Line Items | Two-way |
| Paid Status | Balance = 0 | Two-way |
| QBO Invoice Link | Invoice URL | Import from QBO |
Requirements:
- Invoice must be flagged for accounting sync (
sendToAccounting= true) - Project must be synced to QuickBooks first
Invoice sending: When an invoice is synced to QBO, sending it from Readybuild uses the QuickBooks Online SendEmail API instead of Readybuild's email system. QuickBooks sends the email to the billing address on file and includes a direct payment link. See Sending Invoices for details.
Payment link: During sync, the QBO invoice's hosted payment URL is captured and stored. This link is used on the client-facing invoice detail page and the portal billing page to allow customers to pay directly through QuickBooks Online.
Client Payments
| Readybuild Field | QuickBooks Field | Direction |
|---|---|---|
| Payment Date | Transaction Date | Two-way |
| Amount | Total Amount | Two-way |
| Payment Method | Payment Method Reference | Two-way |
| Invoice | Linked Transaction (Invoice) | Two-way |
| Credit Memo (if applicable) | Linked Transaction (Credit Memo) | Two-way |
Requirements:
- Payment must be flagged for accounting sync (
sendToAccounting= true)
Credit Memos
| Readybuild Field | QuickBooks Field | Direction |
|---|---|---|
| Credit Memo Number | Doc Number (prefixed as CM{number}) | Export only |
| Created Date | Transaction Date | Two-way |
| Title | Private Note | Two-way |
| Project | Customer Reference | Two-way |
| Type (Flat Fee or Line Item) | Line Items | Two-way |
| Amount(s) | Line Item Amounts | Two-way |
Requirements:
- Credit memo must be flagged for accounting sync (
sendToAccounting= true) - Project must be synced to QuickBooks first
Data Not Synced
The following data types do not sync with QuickBooks Online:
- Change Orders - Not supported for QuickBooks Online sync
Conflict Resolution
When the same record is modified in both systems:
- Timestamp-based: The most recent change typically wins
- Webhook priority: Changes from QuickBooks via webhook are applied immediately
- Manual resolution: In rare conflict cases, manual intervention may be required
Next Steps
- Troubleshoot issues if records aren't syncing as expected
- Configure defaults if you haven't set up invoice cost codes