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 |
A project's Display Name is built from its Project ID and Title, and is adjusted to fit what QuickBooks accepts: colons are removed, runs of spaces are collapsed, and the result is shortened to 41 characters. QuickBooks reserves the colon to separate a customer from its sub-jobs, so a name containing one is rejected outright.
Changing a project's Project ID, Title, Contact or Address queues a sync. Other project fields — stage, project manager, estimator, percent complete, description — are not part of the QuickBooks record and do not trigger one.
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 / Pay Type mapping | Item Reference |
| Billable Status | Billable Status |
Item Reference resolution order:
- If the time entry has a cost code that is mapped to a QuickBooks item, that item is used as the Item Reference.
- Otherwise, for PTO and holiday pay types only, the pay type's configured Service Item mapping is used as the Item Reference.
- If neither is configured, the time activity is created without an Item Reference.
Regular and overtime pay types do not use the pay type mapping — they require a cost code to set an Item Reference. This ensures production hours continue to route by cost code while PTO and holiday hours land in the right wage account in QuickBooks.
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
Delete propagation: When an invoice is deleted in Readybuild, the linked QuickBooks Online invoice is also deleted. Any attached payments are deleted too, removing their linked QuickBooks payments. The local link is removed, so a restored invoice comes back unlinked from QuickBooks. Requires the Manage Client Invoicing permission.
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)
Delete propagation: When a payment is deleted in Readybuild, the linked QuickBooks Online payment is also deleted. The local link is removed, so a restored payment comes back unlinked from QuickBooks. Requires the Manage Client Invoicing permission.
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
Delete propagation: When a credit memo is deleted in Readybuild, the linked QuickBooks Online credit memo is also deleted. The local link is removed, so a restored credit memo comes back unlinked from QuickBooks. A credit memo with active payments applied to it cannot be deleted — remove those payments first. Requires the Manage Client Invoicing permission.
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