QuickBooks Sync for Bills

Learn how bills synchronize between ReadyBuild and QuickBooks.

Overview

Bills sync bidirectionally with QuickBooks:

Direction	When
ReadyBuild → QuickBooks	Bill saved with "Send to QuickBooks" enabled
QuickBooks → ReadyBuild	Scheduled sync job or manual import

Both QuickBooks Desktop and QuickBooks Online are supported.

Enabling QuickBooks Sync

Per-Bill Setting

Each bill has a Send to QuickBooks toggle:

1. Open the bill (new or existing)
2. Enable Send to QuickBooks
3. Save the bill

When enabled, the bill syncs on save.

Company-Level Settings

QuickBooks integration must be configured at the company level:

1. Go to Admin → Integrations → QuickBooks Online (or Desktop)
2. Connect your QuickBooks account
3. Configure sync settings

Field Mapping

Bill Header

ReadyBuild	QuickBooks	Notes
bill_number	DocNumber	Auto-generated, unique
vendor_id	VendorRef	Looked up via QuickbooksEntity
due_date	DueDate	Payment due date
invoice_date	TxnDate	Transaction date
title	PrivateNote	Internal notes

Line Items

ReadyBuild	QuickBooks	Notes
Item total	Amount	qty × unit_cost
name	Description	Line description
cost_code_id	ItemRef	Maps to QB Item
qty	Qty	Quantity
unit_cost	UnitPrice	Per-unit price
project_id	CustomerRef	Project as QB Customer

Export to QuickBooks (RB → QB)

When a bill is saved with sync enabled:

1. Bill data mapped to QB format
2. Vendor lookup via QuickbooksEntity table
3. Line items converted with ItemRef and CustomerRef
4. Create or Update sent to QB API
5. QuickbooksEntity record created/updated linking RB and QB records

Requirements for Export

• QuickBooks integration active
• Vendor exists in QB (or gets created)
• Cost codes mapped to QB Items (recommended)

What Gets Created

A Bill record in QuickBooks with:

• Linked to the correct Vendor
• Line items with quantities and prices
• Customer references for project tracking
• Private notes for internal reference

Import from QuickBooks (QB → RB)

When bills are imported from QuickBooks:

1. Basic fields mapped from QB Bill
2. Status determined by Balance and TotalAmt:
   • Balance = 0, TotalAmt > 0 → PAID
   • Balance > 0 → BILLED
3. Line items created with automatic defaults if needed
4. Vendor and project mapped via QuickbooksEntity
5. Title set to "Quickbooks Online Vendor Bill"

Default Handling

When QB line items can't be fully mapped:

• Cost Code: First cost code in your company's list
• Unit: "LS" (Lump Sum) if not specified
• Bills may import as Draft if required fields are missing

Payment Sync

Paying Bills in ReadyBuild

When you mark a bill as Paid:

1. BillPayment job queued if QB connected
2. QB bill balance fetched to determine payment amount
3. BillPayment created in QuickBooks:
   • Payment amount (outstanding balance)
   • Payment type (Check or CreditCard based on paid_by_id)
   • Payment date
   • Link to the original Bill

Payments Made in QuickBooks

When a BillPayment is created in QB:

1. Linked bill found from LinkedTxn
2. QB bill fetched to check remaining balance
3. RB bill updated:
   • Balance = 0 → Status = PAID
   • Balance > 0 → Status = READY_TO_PAY (partial payment)
4. Payment method mapped from QB PayType
5. Payment account ref stored for reconciliation

Void Handling

When a bill is voided in ReadyBuild, the action in QuickBooks depends on company settings:

Delete Mode (Default)

1. All linked BillPayments are deleted from QB
2. The Bill is deleted from QB
3. QuickbooksEntity records are removed

Note Mode

1. BillPayments are kept in QB
2. Bill's PrivateNote updated with "(VOIDED in ReadyBuild)"
3. Use this to maintain QB audit trail

None Mode

No action taken in QuickBooks. Use when:

• You handle voids manually in QB
• You want QB and RB independent

Configuring Void Mode

Contact support or check company settings for: QUICKBOOKS_BILL_VOID_ACTION = delete | note | none

Sync Troubleshooting

Bill Not Syncing

1. Check "Send to QuickBooks" is enabled on the bill
2. Verify QB integration is connected in Admin settings
3. Check for sync errors in the audit log
4. Ensure vendor exists in QuickBooks

Vendor Mapping Issues

If vendor doesn't map correctly:

1. Check QuickbooksEntity table for the contact
2. Verify vendor is synced to QB
3. Manually sync vendor if needed

Line Item Mapping

If line items don't map to QB Items:

1. Ensure cost codes have qbo_list_id set
2. Default Item used if not mapped
3. Consider mapping cost codes to QB Items in admin

Payment Sync Failures

If payments don't sync:

1. Check that bill exists in QB (synced first)
2. Verify QB bill has balance to pay
3. Review payment job logs for errors

Audit Trail

All sync activities are logged:

• Export success/failure with QB entity ID
• Import success/failure with mapping details
• Payment sync with amounts and status changes
• Void actions with mode used

Access logs through:

• Bill's QuickBooks sync status indicator
• Company audit log
• Admin → Integrations → Sync History

Best Practices

1. Map Cost Codes to QB Items

For accurate line item mapping, configure cost codes with QB Item references.

2. Sync Vendors First

Ensure vendors are synced to QB before creating bills for them.

3. Use Consistent Naming

Match vendor names between RB and QB for automatic matching.

4. Review Imported Bills

Bills imported from QB may need review - check cost codes and status.

5. Monitor Sync Status

Regularly check for sync errors and address mapping issues.

6. Understand Void Behavior

Know your company's void mode setting to predict QB behavior.