Overview
This guide walks you through connecting your QuickBooks Online (QBO) account to Wrapbook so payroll data flows automatically into your General Ledger (GL). Setup takes about 15–30 minutes, not including Chart of Accounts (COA) mapping, which can take longer for large charts.
What the integration does
When you issue a payroll in Wrapbook, the integration automatically creates a Bill in QBO's Accounts Payable with a status of Draft. Your AP team reviews and posts the Bill in QBO.
Optional: Bill Payment sync
By default, Bills arrive in QBO with a status of Draft. If you want Bills to arrive as Paid with a matching BillPayment record, contact your Wrapbook Customer Success Manager (CSM) or the Support Team and ask them to enable the QBO Bill Payment feature for your account.
When the feature is enabled:
New Bills arrive as Paid
A matching BillPayment record is created automatically
The transaction is completed immediately in QBO, so no AP review is required
Your bank balance updates immediately in QBO
Existing Draft Bills remain unchanged
You can request that the feature be disabled if you want new Bills to return to the default Draft status.
What flows into QBO
Object | When | Status on arrival |
|---|---|---|
Bill (forward payroll) | When you issue a payroll | Draft (default), or Paid if Bill Payment sync is enabled |
Each Bill includes Wages, Expenses, Reimbursements, Fringes, Platform Fees, and Workers' Compensation as separate line items, plus a Memo field with the Project Name, Payroll ID, and a link back to the payroll in Wrapbook.
What flows back from QBO into Wrapbook
Wrapbook reads the following from QBO to populate your mapping configuration. This direction is read-only:
Chart of Accounts
Vendors
Locations
Class / Customer
Supported dimensions
The integration can pass Customer, Class, and Location on Bill lines, in addition to the GL account itself.
Important: Customer and Class are mutually exclusive per bill line at the QBO API level. If your Granular Mapping Configuration has either Customer or Class active, Project ID cannot also be assigned on that same line—QBO does not allow both. Selecting one effectively disables the other for that line.
If Project ID is set to Not Used, the standard workaround when Customer or Class mapping is required, project-level dimensions will not sync to QBO for any production on the account.
Not supported
Custom Fields: Arbitrary customer-defined QBO fields are not supported
Multi-currency: Your QBO company must be US-based. Multi-currency QBO companies are not supported.
Before you start
Have these ready before scheduling your setup call:
QBO Admin access: Needed to authorize the OAuth connection in Step 1
A “Wrapbook” vendor record in QBO: Create one if it does not exist; the integration does not auto-create vendors.
Project chart template — start from the Wrapbook template or a blank template (for line numbers & sections)
Dimension requirements — know which of Location, Class/Customer, and GL Accounts are required on transaction lines
Step 1: Connect Wrapbook to QBO
In the left-side navigation, under Company, click …More; in the …More menu, click Company settings
On the Company settings page, in the Accounting settings section, click Manage next to Integrations
Find QuickBooks Online and click Setup
You will be redirected to the QBO login page. Log in as an Admin and select the correct company. Confirm that you are logged into the correct QBO account before starting, since switching accounts mid-setup can cause connection issues.
Review the requested permissions and click Connect to authorize
You will be redirected back to Wrapbook with a loading screen while your QBO data is pulled. This can take a few minutes.
Step 2: Set company defaults
Once redirected back to Wrapbook, set:
Vendor: For example, Wrapbook
Bank Account: For example, Checking
Default Expense Account: For example, Employee Wages. This is the fallback inherited by all projects.
Dimensions — go to Company settings → Integrations settings → Edit Dimensions to enable Location, Class /Customer as applicable to your GL requirements
Default payroll description: Customize the description fields that appear on each Bill line. By default, this includes First name, Last name, Job title, Hourly wage, Cost code, and # of days worked. You can add, remove, or reorder these fields to match your AP team's needs.
Select Save Integration Settings.
If accounts or vendors are missing from the drop-down, click Refresh Connection on the Manage Integration page.
Step 3: Configure your Chart Mapping
Before configuring individual projects, set up your Project Chart Template. This is done once and reused across projects.
A. Select the Chart of Accounts
Go to Company Settings → Project chart templates → Edit
Select an AICP or custom chart already mapped at the company level
Each chart line maps to a single GL account. Dimensions are applied separately at push time from project or company defaults; they are not configured per line.
B. Map fringe lines
The project chart template includes fringe-bucket rows—Total Fringes, Employer Taxes, and Platform—that do not auto-populate from your COA. Add these to your project chart and map each to the corresponding GL account. These are typically the employer payroll tax, platform or processing fee, and fringes accounts.
See the Fringe Mapping Reference section at the bottom of this guide for full details on fringe line behavior and recommended GL mappings.
Step 4: Configure each project
After the company-level connection is set up, each Wrapbook project needs the following confirmed before its first payroll sync.
A. Assign the Chart Template
Go to Project Settings → Cost tracking, enable Accounting chart, and select a Chart Template from the dropdown. Use Manage chart to review or adjust the chart's line-level mappings if needed.
B. Set project-level dimension overrides (optional)
Go to Company Settings → Integrations Settings → Edit to override project dimensions using the Feature Dimension Management functionality. Each dimension can be overridden at the project level under the Override project dimensions section. If not overridden, dimensions inherit the company-level defaults.
C. Verify timecard coding is complete
Bills are created automatically at payroll issuance with no manual review step in Wrapbook. However, Bills arrive in Draft status by default, giving your AP team a chance to review before posting. If Bill Payment sync is enabled, Bills will be marked Paid immediately with no draft-stage review. In that case, confirm that timecard coding is complete before issuing payroll.
How coding gaps affect the push depends on the field type:
Required fields (GL account and Vendor): If either is missing, the push will fail entirely — you'll see a "Failed" status in Integration push history
Dimensions: Behavior depends on how each dimension is configured in QBO. If a dimension is marked required in QBO, a missing value will cause the push to fail. If it's optional, the bill will sync but that dimension will be left uncoded on the line.
Bill line descriptions
Use the descriptions below as a quick reference when reviewing a Wrapbook payroll Bill in QBO. The exact number of lines may vary based on project-chart coding and the account's fringe-mapping configuration, but the line category and description pattern should follow these conventions.
Bill line category | What it represents | Typical QBO description |
|---|---|---|
Wages / Labor | Gross pay generated from worker timecards. Taxable other wages are treated as wage/labor amounts when they are classified as wages in Wrapbook. |
|
Allowances / Expenses / Reimbursements | Non-labor payments such as kit or box fees, mileage, meals, and other reimbursements. Taxable and non-taxable classifications remain distinct in the payroll data. |
|
Fringes | Employer-side payroll costs outside gross wages, such as employer taxes, workers’ compensation, union pension and health contributions, and other configured fringe costs. |
|
How to interpret the descriptions:
Wages may include the work dates, worker name, and week-ending date so the labor amount can be traced back to the source timecard
Allowances and reimbursements identify the expense or allowance type before the worker name and week-ending date. The description does not replace the taxable or non-taxable classification in the payroll record.
Fringes use a fringe-specific description rather than the labor description. Depending on your configuration, multiple underlying fringe types may be grouped into a consolidated fringe or employer-fee line, while Platform Fees and Workers’ Compensation may appear separately.
If the underlying payroll lines are not coded to a GL account, the accounting transaction may contain separate lines for individual workdays instead of a consolidated line. Similar lines can also be consolidated when they share the same mapping and scope.
These descriptions are intended to make the Bill easier to reconcile to Wrapbook payroll. They do not change the GL account, dimension, or tax treatment assigned to the underlying payroll line.
After go-live: what to expect
Initial sync on connection
When you enter your credentials, Wrapbook immediately fetches your Chart of Accounts, Vendors, Classes, Locations, and Departments. This data appears in your mapping UI within 2–5 minutes.
Ongoing data refresh
Wrapbook pulls your Chart of Accounts, Vendors, Customers, and Classes from QBO on connection and keeps them updated going forward.
Manual refresh
If you need data to update immediately—for example, if you just added a GL account in QBO:
Go to Company Settings → Integration Settings → Edit
Click Refresh Connection
Updated lists appear within 2–5 minutes
Reconciliation: what the Bill looks like in QBO
Process payroll as normal in Wrapbook
Wrapbook automatically creates a Bill in QBO with a status of Draft, or Paid if Bill Payment sync is enabled
In QBO, go to Expenses → Bills → Open for Draft Bills or Paid for Bills using Bill Payment sync, under the Wrapbook vendor
Wrapbook → QBO field mapping
Wrapbook source | QBO Bill field | Notes |
|---|---|---|
Default vendor (Company Settings → Step 2) | Vendor | Fixed per integration configuration, not derived from the payroll itself |
Payroll issuance date | Bill date | — |
Payroll fund/debit date | Due date | — |
Payroll ID (batch number) | Bill no. | Also duplicated in Memo as “Batch: [ID]” |
Project name | Memo | First line: “Project: [name]” |
Full payroll invoice (PDF) | Attachments | Complete payroll report attached as PDF for AP reference |
Total payroll debit | Total / Payment Status: Paid | Full employer-side debit, not net worker pay; includes wages, reimbursements, fees, and fringes |
Line-item mapping
Wrapbook source | QBO Bill line | Consolidation logic |
|---|---|---|
Employee Wages → Gross Pay | Employee Wage line | One line per worker per rate; posts at gross, not net. Deductions are absorbed into this figure and are not broken out separately. |
Reimbursements (Non-Taxable) | Non-Taxable Reimbursement line | Grouped by Cost Code. Multiple reimbursement entries with the same Cost Code sum into a single bill line. |
Reimbursements (Taxable) | Taxable Reimbursement line | Uses the same grouping logic as non-taxable reimbursements, with taxable and non-taxable lines kept separate. |
Summary → Employer Fees & Contributions | Employer Fees line | One consolidated line |
Summary → Platform Fees | Wrapbook Platform Fees line | One line |
Summary → Workers’ Compensation | Workers Compensation line | One line |
Summary → Employer Union Fringes | Total Union Dues line | One consolidated line; present only when a union CBA applies |
Viewing sync status and syncing payrolls
Check sync status
After a payroll is issued, you can confirm whether the push to QBO succeeded:
Go to Company Settings → Integration Push History
Find the payroll row and look at the Sync Status column
Status | Meaning |
|---|---|
Sync complete | Bill, and matching BillPayment when enabled, pushed successfully to QBO |
Failed | Push attempt failed. Click the row to view the error message. |
Pending | Push is in progress or has not been attempted yet. Wait a few seconds and refresh. |
(empty) | The integration was not connected when the payroll was issued, so no push was attempted. |
Retry a payroll sync
If a payroll missed the auto-push—for example, because the integration was not set up at the time of issuance:
Go to Company Settings → Integration Push History
Find the payroll you want to re-sync and click Retry Sync
Wrapbook re-attempts the push immediately
Check Sync Status after a few seconds to confirm that it succeeded
Deleting the integration
Go to Company settings → Accounting → Integrations → Manage
Click Delete Integration and confirm
If you have any payroll in flight, do not disconnect without talking to Wrapbook Support first. Bills already created in QBO will not sync to a new accounting provider if you switch; only new activity syncs going forward.
Troubleshooting
Troubleshoot a failed push
Find the failure. Go to Company Settings → Integration push history. Locate the payroll row and check the Sync Status column — a status of "Failed" means the push didn't go through.
Read the error message. Click the row to view the specific error and timestamp. This tells you which validation failed (e.g., missing dimension, invalid GL account, unmapped chart line).
Check the likely causes, in order:
Is a Chart Template assigned to the project? Go to Project Settings → Cost tracking and confirm a chart is selected under Enable accounting chart. No chart assigned means any coding is accepted, which can cause downstream mapping gaps.
Does the fringe mapping exist? Go to Project Settings → Project Charts and confirm fringe-bucket rows (Total Fringes, Employer Taxes, Platform) are mapped to GL accounts, not left blank.
Are dimension overrides missing? Check Company Settings → Integrations Settings → Edit → Override project dimensions to confirm required dimensions (Project, Location, Department, Item, Task) are set for this project.
Fix and re-sync. Once the gap is corrected, use the Retry Sync button on the payroll row and confirm Sync Status updates to "Synced" within ~15 seconds.
Common errors
Error / symptom | Cause | Solution |
|---|---|---|
Sync errors on new pay types or deductions | A new pay type or deduction was added without a GL mapping. | Review and update account mappings in the chart template. Use Re-sync Data if the new account does not appear yet. |
QBO authentication failure | The OAuth token expired or access was revoked in QBO. | Reconnect QBO from Company Settings → Accounting Settings → Integrations Setup. This re-triggers the OAuth flow. |
Duplicate vendor entries | Slight naming differences exist between the Wrapbook vendor record and the QBO vendor record. | Manually merge duplicate vendors in QBO. Wrapbook does not auto-merge vendors. |
Missing Class or “line number” errors on sync | Project ID and Customer/Class are both active on the same Granular Mapping Configuration. QBO rejects this combination. | Set Project ID to Not Used if Customer or Class mapping is required. Confirm that the customer understands this disables project-level dimension sync account-wide. |
Accounts or projects missing from mapping dropdowns | Reference data has not synced since the object was created in QBO. | Click Re-sync Data on the Manage Integration page. |
Best practices
Wrapbook recommends the following patterns for QBO customers:
Use Classes for organizational structure: Represent organizational units for more granular reporting and cost allocation
Use Locations for production multi-entities: Map Wrapbook production entities to QBO Locations to track expenses and revenue across production units
Reconcile weekly: Schedule regular reconciliations between Wrapbook and QBO, and review account mappings periodically as the chart of accounts evolves
Need help?
Contact the Wrapbook Support Team or reach out to your Wrapbook CSM if you run into setup issues or have questions about how your specific configuration works with the integration.