QuickBooks Desktop Sync Reference

Complete reference for all data synchronized between Readybuild and QuickBooks Desktop.

Sync Direction Overview

Direction	Description
Export (Readybuild → QB)	Data created in Readybuild is sent to QuickBooks
Import (QB → Readybuild)	Data from QuickBooks is pulled into Readybuild
Bidirectional	Data syncs both ways

Export Entities (Readybuild → QuickBooks)

Customers

Field	QuickBooks Field	Notes
Company Name	Name	Primary identifier
First Name	FirstName
Last Name	LastName
Billing Address	BillAddress	Street, City, State, Zip
Phone	Phone
Alt Phone	AltPhone
Fax	Fax
Email	Email
CC Email	Cc

When Created: Customers are exported when a project is first synced and the associated contact doesn't exist in QuickBooks.

Vendors

Field	QuickBooks Field	Notes
Company Name	Name	Primary identifier
First Name	FirstName
Last Name	LastName
Vendor Address	VendorAddress	Street, City, State, Zip
Phone	Phone
Alt Phone	AltPhone
Fax	Fax
Email	Email
CC Email	Cc
Name on Check	NameOnCheck

When Created: Vendors are exported when a purchase order or bill references a vendor not yet in QuickBooks.

Jobs (Projects)

Field	QuickBooks Field	Notes
Project ID + Title	Name	Format: "P-1234 - Kitchen Remodel"
Parent Customer	ParentRef	Links job to customer
Job Site Address	JobAddress	Project location
Status	JobStatus	Maps to QB job statuses
Start Date	StartDate
Projected End Date	ProjectedEndDate
End Date	EndDate
Description	Notes

When Created: Jobs are created when a project is synced that has a linked customer in QuickBooks.

Invoices

Field	QuickBooks Field	Notes
Customer Reference	CustomerRef	Links to customer/job
Invoice Number	RefNumber
Transaction Date	TxnDate
Line Items
Description	Desc
Quantity	Quantity
Rate	Rate
Cost Code	ItemRef	Via cost code mapping

Bills

Bills are bidirectional. When exporting from Readybuild:

Field	QuickBooks Field	Notes
Vendor Reference	VendorRef
Transaction Date	TxnDate
Due Date	DueDate
Reference Number	RefNumber	Vendor bill number
Memo/Title	Memo
Line Items
Description	Desc
Quantity	Quantity
Cost	Cost
Amount	Amount
Cost Code	ItemRef	Via cost code mapping
Project Reference	CustomerRef	Job reference on line

Estimates

Field	QuickBooks Field	Notes
Customer/Project Ref	CustomerRef
Reference Number	RefNumber
Memo (Name)	Memo
Line Items
Description	Desc
Quantity	Quantity
Cost	Rate
Markup	Markup	Applied per cost code

Credit Memos

Field	QuickBooks Field	Notes
Customer/Project Ref	CustomerRef
Transaction Date	TxnDate
Reference Number	RefNumber
Memo	Memo
Line Items
Description	Desc
Quantity	Quantity
Rate	Rate
Amount	Amount
Cost Code	ItemRef

Purchase Orders

Field	QuickBooks Field	Notes
Vendor Reference	VendorRef
Ship-to Reference	ShipToEntityRef	Project/job reference
Transaction Date	TxnDate
PO Number	RefNumber
Ship Address	ShipAddress
Expected Date	ExpectedDate
Vendor Message	VendorMsg
Line Items
Description	Desc
Quantity	Quantity
Rate	Rate
Amount	Amount
Part Number	ManufacturerPartNumber	If available

Time Tracking

Field	QuickBooks Field	Notes
Transaction Date	TxnDate
Employee Reference	EntityRef	Via employee mapping
Customer/Project Ref	CustomerRef
Service Item Ref	ItemServiceRef
Duration	Duration	ISO 8601 format (PT#H#M#S)
Payroll Item	PayrollItemWageRef	Via payroll code mapping
Notes	Notes
Billable Status	BillableStatus	Billable, NotBillable, HasBeenBilled

Duration Format

Time entries are exported using ISO 8601 duration format. For example, 2 hours and 30 minutes is represented as PT2H30M0S. QuickBooks interprets this format correctly for time tracking.

Import Entities (QuickBooks → Readybuild)

Customer Payments

Field	Readybuild Field	Notes
Payment Amount	amount
Transaction Date	paymentDate
Reference Number	referenceNumber
Payment Method	paymentMethod
Applied-to Invoices	appliedToInvoices	Array of invoice references

Sync Behavior: Payments are imported using incremental sync. By default, the system looks back 1 hour from the last sync to catch any payments that may have been recorded just before the previous sync.

Bills (Import Direction)

When bills are created in QuickBooks, they can be imported into Readybuild:

Field	Readybuild Field	Notes
Vendor Reference	vendor
Transaction Date	billDate
Due Date	dueDate
Reference Number	vendorBillNumber
Memo	title
Line Items	lineItems	Including job references

Matching: Bills are matched to projects based on the Job/Customer reference in the line items.

Reference Data (for Mapping)

These entities are imported to populate mapping dropdowns:

Entity	Purpose
Employees	For employee mapping configuration
Payroll Items	Payroll wage items for pay type mapping
Service Items	Service items for cost code mapping
Sales Tax Items	Sales tax items for tax configuration

Sync Mechanics

Edit Sequence Tracking

QuickBooks uses Edit Sequences to prevent conflicting updates:

1. When Readybuild fetches a record, it stores the current Edit Sequence
2. When updating that record, Readybuild includes the stored Edit Sequence
3. If the sequence doesn't match (record was modified elsewhere), QuickBooks returns an error
4. The integration automatically fetches the new Edit Sequence and retries

This prevents one system from overwriting changes made in the other.

Incremental vs Full Sync

Sync Type	Description	Used For
Incremental	Fetches only records modified since last sync	Bills, Payments
Full	Fetches all records	Initial imports, Refresh actions

Incremental sync uses a fromDate parameter, typically looking back 1 hour to ensure no records are missed due to timing issues.

Iterator Processing

Large datasets are processed in batches:

1. Initial request returns first batch (typically 100 records) plus an iterator ID
2. Subsequent requests use the iterator ID to fetch next batches
3. Process continues until all records are retrieved
4. Prevents timeouts and memory issues with large datasets

Queue-Based Processing

All sync operations use a queue system:

1. Readybuild queues items to send to QuickBooks
2. Web Connector connects and processes the queue
3. Results are sent back to Readybuild
4. Queue items are marked complete or retried on error

Sync Direction Summary Table

Entity	Export	Import	Notes
Customers	✓	Initial only	Ongoing changes don't sync back
Vendors	✓	Initial only	Ongoing changes don't sync back
Jobs (Projects)	✓	Initial only	Ongoing changes don't sync back
Invoices	✓	—
Bills	✓	✓	Bidirectional
Estimates	✓	—
Credit Memos	✓	—
Purchase Orders	✓	—
Time Entries	✓	—
Payments	—	✓
Employees	—	✓	For mapping only
Payroll Items	—	✓	For mapping only
Service Items	—	✓	For mapping only

Related Documentation

• Configuration - Set up mapping rules
• Troubleshooting - Handle sync errors
• Project Linking - Manual linking options