QuickBooks Online Match & Link
Match & Link reads records out of QuickBooks Online in bulk, automatically links the ones it can identify with certainty, and hands you the rest to review by hand.
You will use it in two ways:
- Onboarding — connecting a QuickBooks company that already contains years of history, one step at a time, before you turn sync on.
- An ongoing feed — pulling a record type Readybuild doesn't capture on its own, on a repeating schedule. See Keeping Time Data Flowing Weekly.
Match & Link works in the opposite direction from Entity Linking:
| Tool | Starts from | Scale | Use it when |
|---|---|---|---|
| Match & Link | QuickBooks records | Bulk — the whole entity type at once | Connecting an existing QuickBooks company during onboarding |
| Entity Linking | Readybuild records | One record at a time | Fixing a single unlinked contact, project, or transaction later |
Match & Link only creates links — it never pushes data to QuickBooks. Sync direction must be Disabled while you work, and you turn it on afterward. Running sync first can create duplicate records that Match & Link then has to untangle.
Before You Start
Three conditions must be met before a step will run.
Sync direction must be Disabled
Each entity's sync direction must be set to Disabled in Settings > Integrations > QuickBooks Online > Sync Direction. If it isn't, the step shows a warning instead of a runnable button:
Sync direction for Step Name must be set to Disabled before using Match & Link. Change it in QBO settings.
Cost Codes and Employees have no sync direction setting, so they can always run.
Dependencies must be complete
Steps build on each other. A step whose prerequisites haven't been run shows:
Dependencies not met. Complete these steps first: step names
| Step | Requires first |
|---|---|
| Cost Codes, Employees, Vendors, Customers | Nothing |
| Projects | Customers |
| Vendor Credits, Bills, Purchases | Cost Codes, Vendors, Projects |
| Invoices, Credit Memos | Cost Codes, Projects |
| Time Activities | Employees, Projects |
Working straight down the step list in order satisfies every dependency.
Only one run at a time
Your company can have one Match & Link run active at a time. Starting a second returns:
A Match & Link run is already in progress for this company
For Bills and Invoices this includes the payment phase that follows the main run — wait for the payment progress bar to finish before starting the next step.
Accessing Match & Link
- Go to Settings > Integrations
- Click Configure next to QuickBooks Online
- Click Match & Link
The page shows the Match & Link Utility step list on the left and the results panel on the right. Until you open a run, the right side reads Select a step and click "View Results" to see run details.
The Steps
The eleven steps run in a fixed order. Each pulls one QuickBooks record type.
| # | Step | Pulls from QuickBooks | Type |
|---|---|---|---|
| 1 | Cost Codes | Items | Match |
| 2 | Employees | Employees | Match |
| 3 | Vendors | Vendors | Match |
| 4 | Customers | Customers (not jobs) | Match |
| 5 | Projects | Customers flagged as jobs | Match |
| 6 | Vendor Credits | Vendor Credits | Import only |
| 7 | Bills | Bills, then Bill Payments | Match |
| 8 | Invoices | Invoices, then Payments | Match |
| 9 | Credit Memos | Credit Memos | Match |
| 10 | Time Activities | Time Activities | Import only |
| 11 | Purchases | Purchases | Import only |
Match steps look for an existing Readybuild record and link the two together. Import only steps skip matching entirely and create new Readybuild records from every QuickBooks record they find — their button reads Import rather than Run.
A step shows a green check once it has completed, plus a Last run date.
Running a Step
- Click a step name in the left panel to expand it
- Click Run (or Import on an import-only step)
- Choose a mode from the menu:
- Full Run / Full Import — every QuickBooks record of that type
- Since Last Run / Import Since Last Run — only records changed in QuickBooks since the step last completed
- Watch the progress bar, then click View Results
While a step runs you see Processing: n / total with a progress bar and live count chips: Linked, Skipped, Pending, and Errors — or Imported and Skipped on import-only steps.
Bills and Invoices run in two phases. Once the bills or invoices themselves finish, a second bar appears — Processing payments: n / total — while Readybuild pulls the bill payments or payments attached to the records it just linked. Records that didn't link have no payments to pull.
Use Full Run the first time. After that, Since Last Run only re-reads QuickBooks records modified since the last completed run of that step, which is much faster on large companies.
Import-Only Steps
Vendor Credits, Time Activities, and Purchases have no matching phase. Readybuild does not look for an existing Readybuild record — it creates one from every QuickBooks record it pulls. Their button reads Import rather than Run, and the mode options are Full Import and Import Since Last Run.
Because they create records, these steps depend on the linking steps that came before: an imported record has to attach to an employee, project, vendor, or cost code that is already linked. Anything that can't resolve comes back as an Error row explaining what is missing.
Importing Time Activities
Time Activities brings QuickBooks time entries into Readybuild as job-costed time.
Before you start: the Employees and Projects steps must be complete, and the sync direction for time entries must be set to Disabled.
- Go to Settings > Integrations
- Click Configure next to Quickbooks Online
- Click Match & Link
- Scroll the step list and click Time Activities
- Click Import, then choose Full Import or Import Since Last Run
The results panel opens automatically when the import finishes. Each QuickBooks time activity ends in one of three states:
| Result | Meaning |
|---|---|
| Created | A Readybuild time entry was created and linked to the QuickBooks record |
| Skipped | Already imported — this QuickBooks record was brought in by an earlier run |
| Error | Something the entry depends on is missing. The Reason column names it |
The live progress chips during the import read Imported, but once you open the results panel those same rows are labelled Created. They mean the same thing.
Common Time Activities errors
| Reason | Fix |
|---|---|
| Employee with QBO ID n is not linked in ReadyBuild | Run or finish the Employees step, then retry the row |
| TimeActivity has no CustomerRef — job cost import requires a project | The QuickBooks time entry isn't assigned to a customer or job. Assign it in QuickBooks, then re-import |
| Customer with QBO ID n is not linked to a ReadyBuild project | Run or finish the Projects step, then retry the row |
| Cost code with QBO Item ID n is not linked in ReadyBuild — link it via the Cost Codes step and retry | Link that item on the Cost Codes step, then retry the row |
| Company has no regular pay types configured — cannot import time | Set up at least one regular pay type under Pay Types, then retry |
Fix the underlying cause first, then use Retry on the row or Retry All Errors (n) to reprocess everything at once. Retrying re-runs the import — you don't need to start the step over.
Keeping Time Data Flowing Weekly
If your crews record time in QuickBooks rather than in Readybuild, you can run the Time Activities import on a repeating schedule and treat it as your time feed. Readybuild then has the labor hours it needs for job costing without anyone re-keying them.
The weekly routine:
- Open Match & Link and click Time Activities
- Click Import, then choose the mode:
- Full Import the first time, to bring over your existing QuickBooks time history
- Import Since Last Run every week after that
- Review the results and clear any Error rows
Import Since Last Run pulls only the QuickBooks time activities changed since the last time the step finished, so each week's run is short.
Every imported time activity is recorded against its QuickBooks ID. A record that was already brought in comes back as Skipped — Already imported, so re-running the step, or running Full Import to catch anything you missed, never creates duplicates.
What the QuickBooks entry needs
For an imported entry to reach job costing, the QuickBooks time activity must carry all three of these, each pointing at something already linked in Readybuild:
| QuickBooks field | Must resolve to | If it's missing |
|---|---|---|
| Employee | A linked Readybuild team member | The row errors |
| Customer / Job | A linked Readybuild project | The row errors |
| Item | A linked Readybuild cost code | The entry imports, but Readybuild marks it non-billable and job costing ignores it |
The Item is the one to watch. A time activity with no item still imports successfully — it just never shows up against a cost code. If job costing looks light after an import, check whether the QuickBooks entries carried items.
How the imported time is costed
- Labor cost uses the Readybuild employee's labor rate, not any rate stored in QuickBooks
- Pay type is set to your first regular pay type — QuickBooks pay types are not carried over
- Each imported activity creates its own time entry rather than merging into a weekly timesheet
Committed vs. approved cost
Imported time lands unapproved. On the job costing screen it appears as committed cost until the timesheet week that covers it is approved, at which point it moves to approved labor cost. Approving weeks as you go keeps job costing showing actual rather than committed labor.
Time entry sync direction must stay set to Disabled for this to keep working. Turning it on makes Readybuild push time back to QuickBooks, which is the opposite of what you want here.
How Matching Works
The rule that governs everything:
- Exactly one candidate found — the records are linked automatically and marked Linked
- No candidate found — the record is marked Pending for you to link by hand
- Two or more candidates found — the record is marked Pending with a reason ending requires manual selection
Match & Link never guesses between two possible matches. Records already linked to QuickBooks are marked Skipped with the reason Already linked.
Match rules by step
| Step | How a match is found |
|---|---|
| Cost Codes | Exact QuickBooks item name against the cost code name; failing that, a leading number in the item name (100 Framing, 100-Framing, 100.10) against the cost code number |
| Employees | An existing QuickBooks ID on the team member; then primary email address; then first and last name |
| Vendors | Company name; then first and last name; then QuickBooks display name against company name |
| Customers | Same rules as Vendors, against contacts rather than vendors |
| Projects | The parent QuickBooks customer must already be linked. Then the job's display name against the project title, scoped to that customer's projects |
| Bills | QuickBooks document number against the Vendor Bill Number |
| Invoices | QuickBooks document number against the invoice number |
| Credit Memos | QuickBooks document number against the credit memo number |
| Payments and Bill Payments | The linked invoice or bill, plus amount and date |
A project whose parent customer isn't linked yet reports Parent customer "Name" (QBO ID: n) is not linked — link the customer first. Run the Customers step first, or use the Link Customer button on the row.
Reviewing Results
Click View Results on a step to open the Step Name Results panel.
Filtering
The count chips across the top double as filters — click one to show only those rows, click again to clear:
| Chip | Meaning |
|---|---|
| Linked | Connected to a QuickBooks record |
| Skipped | Nothing to do — usually already linked |
| Created | A new Readybuild record was created by an import |
| Pending | Needs you to pick a match |
| Importing | An import is in progress on this row |
| Errors | The link or import failed |
The results table
| Column | Shows |
|---|---|
| QBO Entity | The QuickBooks record type |
| QBO ID | The QuickBooks ID. Click it to open the raw QuickBooks record in a side panel, with a Filter fields... search box |
| Detail | The QuickBooks record's name or number. When the row is linked, this opens the matching Readybuild record in a new tab |
| Action | The status chip |
| Reason | Why Match & Link reached that result. Hover to read a long reason in full |
| Actions | Link, Link Customer, Unlink, or Retry, depending on status |
On Bills and Invoices, payment rows appear indented beneath the bill or invoice they belong to.
Payment rows are grouped under their parent only within the page you are viewing. If a bill lands at the end of one page and its payment at the start of the next, they appear separately. Filter to a single status to bring related rows together.
Linking a Record Manually
- Find a Pending row and click Link
- The Link to Readybuild Type dialog opens, showing the QuickBooks record at the top
- Type in the Search Readybuild Type box — the helper text under the box tells you what that step searches on (bill number, PO number, company or contact name, and so on)
- Click the correct record in the results list
- Click Link
The row changes to Linked with the reason Manually linked by user.
Linking a project's parent customer
If a project row failed because its parent QuickBooks customer isn't linked, the row's button reads Link Customer instead. Use it to link the customer without leaving the results panel — Readybuild then retries the project row automatically.
Creating a cost code from QuickBooks
On the Cost Codes step, the link dialog also offers Create Cost Code, with two options: Production Cost Code and Design Cost Code. Readybuild pre-fills the name from the QuickBooks item, creates the cost code, and links it in one step.
Fixing Errors
A row marked Error means the link itself failed to save. The reason column explains why.
- Click Retry on a single row to run it through matching again
- Click Retry All Errors (n) at the top of the panel to retry every error row in the run
When a run ends with errors still outstanding, the panel shows:
This run completed with errors. Review error entries below.
Retrying successfully clears the banner. A row whose QuickBooks data was never stored cannot be retried — re-run the step instead.
Unlinking
- Click Unlink on a linked row to disconnect that pair
- Click Unlink All (n) to disconnect every linked row in the run
Unlinking deletes only the connection. Neither the Readybuild record nor the QuickBooks record is changed or deleted, and the row returns to Pending so you can link it to something else.
Importing the Remainder
Once you have manually linked everything that has a genuine counterpart, the rows still marked Pending are QuickBooks records with no equivalent in Readybuild. Import Remaining (n) creates them.
This is available on Customers, Vendors, Projects, Bills, and Invoices only.
- Click Import Remaining (n)
- Read the confirmation dialog — it states how many records will be created
- Click Yes, Import All Remaining
Imported rows finish as Created with the reason Imported from QBO. On Bills and Invoices, the payments attached to those records are imported too.
This action creates new Readybuild records for every remaining unmatched QuickBooks entity. If any of them already exist in Readybuild and simply failed to match, you get a duplicate. Work through the Pending rows and link every real match before importing.
When the dialog mentions unmatched payments or bill payments, that number is counted from the page of results you are currently viewing, not the whole run. The main count — the one in the button and the bold number in the dialog — covers the entire run.
After Matching
When every step shows a green check:
- Review each step's results one last time — no unexplained Pending or Error rows should remain
- Go to Configuration and set each entity's Sync Direction to how you want it to run day to day
- Save. Normal syncing takes over from here, using the links Match & Link established
Leave any entity you are feeding by import — time activities, for example — set to Disabled, and keep running its step on your own schedule.
Run history and results are kept for about 60 days, so you can reopen a completed run to check what happened. After that the records are cleaned up automatically.
Related Documentation
- Entity Linking — link individual records after onboarding
- Configuration — sync direction and default mappings
- Sync Reference — what data flows in each direction
- Troubleshooting — common errors and FAQ