--- title: "Set up QuickBooks Online (QBO) in Wrapbook" slug: "set-up-the-quickbooks-online-qbo-integration-in-wrapbook" updated: 2026-11-18T19:45:01Z published: 2026-11-18T19:45:01Z canonical: "help.wrapbook.com/set-up-the-quickbooks-online-qbo-integration-in-wrapbook" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.wrapbook.com/llms.txt > Use this file to discover all available pages before exploring further. # Set up QuickBooks Online (QBO) in Wrapbook > [!NOTE] > Permission required > > To set up the QBO integration, your account must have one of the following [roles](/v1/docs/roles-permissions) enabled: > > - Role: Company Admin > - Custom role with: Company settings/Accounting settings — Full access ## 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](/v1/docs/how-to-get-help-using-wrapbook) 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](/v1/docs/set-up-the-quickbooks-online-qbo-integration-in-wrapbook#e54a562e-ede1-47ca-bbb7-a077911e429a) - **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 1. In the left-side navigation, under *Company*, click ***…More***; in the *…More* menu, click **Company settings** 2. On the *Company settings* page, in the *Accounting settings* section, click **Manage** next to *Integrations* 3. Find QuickBooks Online and click **Setup** 4. 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. 5. Review the requested permissions and click **Connect** to authorize 6. 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](/v1/docs/chart-of-accounts-coa#projectlevel-vs-companylevel-coa). This is done once and reused across projects. ### A. Select the Chart of Accounts 1. Go to **Company Settings → Project chart templates → Edit** 2. 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 Fringe costs are mapped on the chart’s *Fringe mapping rules* tab. For instructions, see [Map fringe costs with fringe mapping rules](/v1/docs/map-fringe-costs-with-fringe-mapping-rules). If the chart previously used fringe-line mappings, Wrapbook carried those mappings over to the *Fringe mapping rules* tab. ## 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](/v1/docs/map-fringe-costs-with-fringe-mapping-rules), 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. | `Labor: Timecard: [work dates], [worker name] - W/E [week-ending date]` | | **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. | `Expenses: [allowance or expense type], [worker name] – WE [week-ending date]` | | **Fringes** | Employer-side payroll costs outside gross wages, such as employer taxes, workers’ compensation, union pension and health contributions, and other configured fringe costs. | `Fringes: [worker name] - W/E [week-ending date]` | **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: 1. Go to **Company Settings → Integration Settings → Edit** 2. Click **Refresh Connection** 3. Updated lists appear within 2–5 minutes ## Reconciliation: what the Bill looks like in QBO 1. Process payroll as normal in Wrapbook 2. Wrapbook automatically creates a Bill in QBO with a status of **Draft**, or **Paid** if Bill Payment sync is enabled 3. 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: 1. Go to **Company Settings → Integration Push History** 2. 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: 1. Go to **Company Settings → Integration Push History** 2. Find the payroll you want to re-sync and click **Retry Sync** 3. Wrapbook re-attempts the push immediately 4. Check **Sync Status** after a few seconds to confirm that it succeeded ## Deleting the integration 1. Go to **Company settings → Accounting → Integrations → Manage** 2. Click **Delete Integration** and confirm **If you have any payroll in flight, do not disconnect** without talking to [Wrapbook Support](/v1/docs/how-to-get-help-using-wrapbook) 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 **Understand a failed payroll push** When Wrapbook cannot send a payroll transaction to QuickBooks Online, the payroll push shows **Failed**. You can review a plain-language explanation before correcting the issue and retrying the sync. **Review the failure** 1. Open the failed payroll push 2. Click **Why did this fail?** 3. Review the explanation in the drawer 4. Review each cause listed in the drawer The explanation summarizes the accounting-system error in plain language. It may identify a missing or incorrect mapping for the chart of accounts, project, department, account, class, customer, location, project task, or cost code. The drawer may show more than one cause. Review every listed cause because you may need to correct settings in more than one place. **Correct the issue** If the drawer includes an action link, click the link to open the relevant settings area. Depending on the cause, the link may open the *Dimensions* grid in *Integration Settings* or *Cost Tracking* in *Project Settings*. If no action link appears, use the cause description to identify the setting that needs attention. Some corrections require a Company Admin, an accounting-system administrator, or a change in QuickBooks Online. **Retry the payroll sync** 1. Correct each issue listed in the drawer 2. Return to the failed payroll push 3. Click **Retry Sync** 4. Review the new sync status After you click **Retry Sync**, the push changes to **Pending** and then to **Success** or **Failed**. If you retry before correcting the underlying issue, the push may fail again for the same reason. #### Permissions Viewing failure explanations is perm[ission based. You must have access to the](/v1/docs/roles-permissions) company-level accounting features to review the explanation and correct settings in Wrapbook. Some corrections may also require a *QuickBooks Online administrator*. ### 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: 1. **Use Classes for organizational structure:** Represent organizational units for more granular reporting and cost allocation 2. **Use Locations for production multi-entities:** Map Wrapbook production entities to QBO Locations to track expenses and revenue across production units 3. **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](/v1/docs/how-to-get-help-using-wrapbook) 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. Original and detailed book of record for all accounting transactions arranged by departmental account codes that occurs throughout the lifetime of a production. The master list of all the accounts used to track production costs, expenses, assets, liabilities, and income. These also can be referred to as Cost Accounts. In commercials, typically AICP line numbers are utilized in its stead. (Accounts Payable) Cash disbursements through the payment of vendor invoices and other payables (Open Authorization) OAuth is a secure way for apps and websites to access your information from another service without asking for your password. It lets you sign in or share limited data safely by granting permission through a trusted provider, like Google or Apple. For example, when you click *Sign in with Google* you're using OAuth. Google confirms who you are, and the app gets access without ever seeing your password. A company or individual providing a product or service. Association of Independent Commercial Producers: Association of producers that handles collective bargaining The additional employer's cost of hiring labor over and above salary; includes statutory charges such as payroll taxes as well as benefits negotiated under a collective bargaining agreement. Legal document used to record employee's hours worked each week. Recording entries to the general ledger in the computer accounting system. Usually refers to a regular payment, not wages, made to a person who has fulfilled certain conditions of services reached a certain age. A specific retirement plan related to union or guild of the entertainment industry. (Collective Bargaining Agreement) refers to agreements between unions and employers that cover workers' terms and conditions.