QuickBooks® Online Integration Overview

User Personas: Admin | Project Manager

Keeping two databases of foundational data up to date by hand is time consuming, and manually transferring data from one software to another leads to errors. eSUB's QuickBooks® Online (QBO) integration eliminates double entry by syncing foundational records between the two systems and sending approved timecard data directly to QBO. The integration is built into eSUB Fusion. You connect, configure, monitor, and disconnect it from within the web application.

This guide covers everything you need to plan, set up, and use the integration: what syncs and in which direction, how to connect, how to configure sync settings and map records, and how to resolve sync errors.

If your organization used the earlier version of the QBO integration (connected through a third-party service), that version has been retired. Your connection was migrated, and you may have been asked to re-authorize QuickBooks® Online from within eSUB Fusion. Contact support@esub.com if your integration shows as disconnected.

Use the links below to jump to a topic:

• Before You Begin
  • Supported Editions
  • Requirements
  • Prepare Your Data
• How the Connection Works
• Field Mapping Reference Points
• Initial Setup
  • Connect eSUB and QBO
  • Choose What to Import from QBO
• Configure Sync Settings
• Map Your Data
• Detailed Data Mapping and Considerations
  • Cost Codes (QBO Service Items)
  • Crew Members (QBO Employees)
  • Contacts (QBO Customers)
  • Supplier Contacts (QBO Vendors)
  • Projects
  • Timecards (QBO Time Activities)
• Sync Timecards to QBO
• Monitor Sync Errors
• Common errors and their resolutions:
• Disconnect from QBO
• Permissions
• FAQ

Before You Begin

Consult with your eSUB Strategic Consultant to determine your desired integration settings and data flow before connecting the integration. Decisions you make before the first sync, such as which records to import and how projects will be linked, are much easier than reconciling data afterward.

When setting up your eSUB database, turn on the QuickBooks® Online integration before adding cost codes, projects, and/or crew members. This ensures you will not have sync/linking issues that require reconciling your data.

Supported Editions

Requirements

To use the QBO integration, you must have the following:

• A compatible edition of QuickBooks® Online (see Supported Editions above).
• Purchase of an eSUB Base or Advanced package + QuickBooks Online integration Add-On.
  • Contact your Sales Executive or Client Success Manager (CSM) for additional information.
• User permission settings for the user performing the setup:

  • Integrations > Accounting: select View and Edit.

    

  • Timecard Management > Sync to Accounting Package is set to Yes.

    

Permissions are managed by permission group. See Set Up User Permissions.

Prepare Your Data

1. Review data in QuickBooks® Online prior to the initial connection. Archive or inactivate any Customers, Vendors, Service Items, or Employees that you do not want pulled into eSUB by the integration.
2. Confirm Projects are enabled in QuickBooks® Online (Account and Settings > Advanced > Projects) if you plan to sync eSUB projects to QBO.
3. Decide with your Strategic Consultant which records you will import from QBO and which you will map manually.

How the Connection Works

The integration connects your eSUB Fusion company to your QuickBooks® Online company using a secure Intuit authorization (OAuth) flow. Your QBO credentials are never stored in eSUB.

• Connect: An admin selects Connect on the Integrations page in eSUB Fusion web. The QuickBooks® sign-in opens in a dialog where you authorize the connection.
• Connection status: Once connected, the Integrations page displays a Connected status along with the date and time the connection was established.
• Initial import: After connecting, an import dialog lets you choose which QBO records to bring into eSUB.
• Configuration: The mapping and settings tabs on the Integrations page become available once the connection status is Connected. While disconnected, those tabs are unavailable.

• Disconnect: You can terminate the connection at any time by selecting Disconnect on the Integrations page.

  

Field Mapping Reference Points

The integration syncs bi-directionally: foundational records (contacts, cost codes, employees) flow from QBO into eSUB, while projects and approved timecards flow from eSUB into QBO.

In summary:

• New QuickBooks Customers will create new Contacts in eSUB's Contact Log.
• New QuickBooks Vendors will create new Contacts (with the Supplier Business Type) in eSUB's Contact Log.
• New QuickBooks Employees will create a new Crew Member in eSUB's User Log.
• New QuickBooks Items (Type: Service) will create new eSUB company-level Cost Codes.
• Projects sync in either direction: new eSUB Projects can create a new Sub Customer in QBO, new QBO projects (sub-customers) can create Projects in eSUB, or projects can be manually mapped from the Project Mapping tab. Project push and pull cannot both be turned on; see Projects below.
• Approved Timecards will be available to be synced into QuickBooks® Online to create new Time Activities.

For field-by-field detail and per-record considerations, see Detailed Data Mapping and Considerations below.

Initial Setup

Connect eSUB and QBO

1. Navigate to Settings > Integrations > Accounting on the global navigation menu. You will be directed to the Overview tab by default.

2. Select Connect.

   

3. The QuickBooks® authorization opens in a dialog. Sign in with your QuickBooks® Online credentials and authorize eSUB to access your QBO company

4. The connection modal will also display the connection progress and allow you to return to the Authorization

   

5. Once a successful login and connection is made, the status updates to Connected and displays the date and time the connection occurred. The Connect button is replaced by a Disconnect button, which you can use at any point to terminate the connection.

Choose What to Import from QBO

Upon successful connection, an import dialog appears letting you choose which QuickBooks® Online records to import into eSUB:

• Customers (created as eSUB Contacts)
• Vendors (created as eSUB Contacts with the Supplier business type)
• Employees (created as eSUB Crew Members)
• Cost Codes (QBO Service Items, created as company-level Cost Codes)

Select the applicable items, then confirm. It may take a few minutes to complete the initial sync process.

Configure Sync Settings

The Settings tab on the Integrations page controls which record types sync automatically. Use it to pick and choose what flows between eSUB and QBO. For example, you may not want to sync Contacts or Vendors but do want to sync Cost Codes.

1. Select Settings > Integrations > Accounting on the global navigation menu.
2. Select the Settings tab.
3. Turn automatic syncing on or off per record type:
   • Pull Customer Contacts from QBO.
   • Pull Vendor Contacts from QBO.
   • Pull Employees from QBO.
   • Pull Cost Codes from QBO.
   • Pull Projects from QBO.
   • Push Projects to QBO.

Project syncing is one direction at a time: you can pull projects from QBO or push projects to QBO, but not both. Decide your project data flow with your Strategic Consultant before enabling either option.

Review your sync settings with your Strategic Consultant before turning syncs on. Once records begin flowing, turning a sync off stops future syncs but does not remove records that were already created.

Map Your Data

Records that exist in both systems are linked through the mapping tabs on the Integrations page. Records imported through the integration are linked automatically; use the mapping tabs to link records that were created separately in each system, and to verify existing links.

Select Settings > Integrations > Accounting on the global navigation menu, then select the applicable tab:

• Project Mapping: Link eSUB projects to QBO projects or sub-customers.
• Cost Code Mapping: Link eSUB company Cost Codes to QBO Service Items.
• Crew Mapping: Link eSUB Crew Members to QBO Employees.

All mapping tools work the same way: for an unlinked eSUB record, select the corresponding QBO item from the drop-down menu, then select Link.

Employees imported from QBO are linked to their eSUB Crew Member automatically. You do not need to hand-link records that the integration created.

After mapping, verify your data in both systems. Automatic syncs run approximately every 5 minutes.

Detailed Data Mapping and Considerations

This section details each integration record type and the specific information that transfers. Items in parentheses are the QuickBooks® Online terms.

Cost Codes (QBO Service Items)

When a new Service Item (within Products & Services) is created in QuickBooks® Online, a corresponding Cost Code is created in eSUB.

* Required fields.

Considerations:

• Only Items with type Service or Non-Inventory are created as eSUB Cost Codes. All other item types (Inventory, Category, Bundle, and so on) are skipped.
• A SKU must be entered in QBO to sync the Item into eSUB. SKUs may contain letters, numbers, and the characters # . , _ and -. Items with other special characters in the SKU will not sync.
• The Item Name must be 50 characters or less.
• Items are created as "Labor" category Cost Codes in eSUB by default. Review your Cost Code company settings with your Strategic Consultant or Client Success Manager.
• If an Item is deleted or made inactive in QBO, the corresponding eSUB Cost Code is deactivated.
• If an identical Cost Code Name and/or Number already exists in eSUB, a duplicate will not be created.

Crew Members (QBO Employees)

When a new Employee (within Payroll) is created in QuickBooks® Online, a corresponding Crew Member is created in eSUB.

* Required fields.

Considerations:

• Only active Employees pull into eSUB. If there is no Employee ID on the Employee page in QBO, eSUB autogenerates the Employee Number using the Employee's display name (or first and last name if no display name exists).
• An Employee will not pull into eSUB if an employee "Release Date" has been added in QBO.
• If an Employee is already synced to eSUB and is then made inactive in QBO (for example, a "Release Date" is added), the corresponding eSUB Crew Member status automatically updates to Unavailable. The integration checks QBO daily for deactivated Employees, so records made inactive at any time are caught.
• If a deactivated Employee is made active again in QBO, the corresponding eSUB Crew Member is reactivated.
• If an Employee's Name or Employee ID is changed in QBO, the corresponding Crew Member Name and Employee No. update in eSUB. (This only occurs if the Crew Member was originally created via the integration.)
• If the Crew Member Name already exists in eSUB, a duplicate will not be created.

Contacts (QBO Customers)

When a new Customer (within Customers & Leads) is created in QuickBooks® Online, a corresponding Contact is created in eSUB.

* Required fields.

Considerations:

• If the QBO Company Name is blank, the Customer Display Name populates the Business Name in eSUB.
• The available contact Business Types in eSUB are Consultant, GC, Supplier, Owner, Subcontractor, and Architect. The QBO contact defaults to the GC contact type if no Customer Type is entered or if the Customer Type does not match an applicable eSUB Contact Business Type.
• Customers in QBO will not pull into eSUB if they are marked Inactive.
• QBO sub-customers flagged as projects are not created as Contacts; they sync as Projects when project pull is enabled (see Projects).
• If changes are made to the QBO Customer profile, the linked eSUB Contact updates automatically.
• If an identical Customer Contact Name and Business Name already exists in eSUB, a duplicate will not be created.

Supplier Contacts (QBO Vendors)

When a new Vendor (within Expenses) is created in QuickBooks® Online, a corresponding Contact (with business type Supplier) is created in eSUB.

* Required field.

Considerations:

• If the QBO Company Name is blank, the Vendor Display Name populates the Business Name in eSUB.
• Vendors in QBO will not pull into eSUB if they are marked Inactive.
• If changes are made to the QBO Vendor profile, the linked eSUB Supplier Contact updates automatically. If a Vendor is deleted or made inactive in QBO, the corresponding eSUB Contact is deactivated.
• If an identical Supplier/Vendor Contact Name and Business Name already exists in eSUB, a duplicate will not be created.

Projects

Projects can be linked between eSUB and QuickBooks® Online in three ways: pull projects from QBO into eSUB, push eSUB projects to QBO, or map existing projects manually. Pull and push are controlled on the Settings tab and cannot both be turned on at the same time.

Option 1: Pull projects from QBO. When project pull is enabled, projects in QuickBooks® Online (sub-customers flagged as projects) create corresponding Projects in eSUB.

Considerations:

• Only active QBO projects and sub-customers pull into eSUB. QBO records that contain person-name or phone fields are treated as people, not projects, and are skipped.
• The eSUB project number is assigned automatically using the next suggested project number.
• If a project is made inactive in QBO, the corresponding eSUB Project is deactivated. The integration checks QBO daily for deactivated projects.
• If an identical Project already exists in eSUB, a duplicate will not be created.

Option 2: Push eSUB projects to QBO. When project push is enabled and a new Project is created in eSUB, a corresponding Sub-Customer is created in QuickBooks® under the Customer eSUB Projects.

Considerations:

• Projects must be enabled in QuickBooks® Online (Account and Settings > Advanced > Projects).
• The project status in eSUB must be set to Open to sync to QuickBooks®.
• The eSUB project is created as a Sub-Customer within the eSUB Projects Customer in QuickBooks®. You can change the Customer association within QuickBooks® or convert the Sub-Customer to a QBO Project.
• If an identical Sub-Customer already exists in QuickBooks® Online, a duplicate will not be created.

Option 3: Map to an existing QuickBooks® Online project. Once a project exists in both QuickBooks® Online and eSUB Fusion, link the two so time can be mapped into QBO:

1. Confirm the project is created in both QuickBooks® Online and eSUB Fusion.
2. Select Settings > Integrations > Accounting from the global navigation menu.
3. Select the Project Mapping tab.

4. For any unlinked eSUB Fusion project, select the drop-down menu under the Accounting Project column, click the corresponding QuickBooks® Online project, then select Link.

   

Alternatively, Projects can be linked when creating a new project or editing an existing project. When creating a new project, ensure the project is created in QuickBooks® Online. For an existing project ensure that the project exists in both QuickBooks® Online and eSUB Fusion.

From the Project Info Tab:

1. Select Edit then navigate to the Accounting Integration subheading
2. Select the drop-down menu box to select the QuickBooks® Online project to link the eSUB Project.

Timecards (QBO Time Activities)

Considerations:

• Only timecards with Approved or Exported statuses in eSUB can be synced to QuickBooks® Online.
• The Crew Member, Project, and Cost Code on the timecard must all be linked between eSUB and QBO for the sync to succeed. If any of the three is unmapped, the timecard is rejected and the failure appears in the Error Log.
• Regular, Overtime, and Double Time hours sync as separate time entries. QBO records the hours of each entry in Total Hours; QBO does not track overtime as a separate category.
• Zero-hour and negative-hour timecard records in eSUB cannot be synced to QuickBooks® Online.
• Records that are currently in the process of being synced are omitted if selected for sync again. Sync can be attempted again once the record has finished processing.
• To sync a timecard, the user must have the Timecard Sync permission set to Yes within their applicable group's user permissions.

Sync Timecards to QBO

Day to day, the integration's main workflow is pushing approved time to payroll. Timecards are synced on demand from Time Management after approvals are made in eSUB. The crew member, project, and cost code on the timecard must be linked between the two systems for the sync to succeed.

For step-by-step instructions, see the timecard sync steps in Time Management.

If a timecard will not sync, first confirm the Crew Member, Project, and Cost Code on that timecard are all mapped (see Map Your Data), then check the Error Log for the specific reason.

Monitor Sync Errors

If a record fails to sync between eSUB and QuickBooks® Online, the failure is recorded in the Error Log on the Integrations page so you can identify the record, understand why it failed, and take action.

Common errors and their resolutions:

If an error persists after correcting the record and re-syncing, contact support@esub.com.

Disconnect from QBO

1. Navigate to Integrations on the global navigation menu.
2. On the Overview tab, select Disconnect.

Disconnecting stops all syncing between eSUB and QuickBooks® Online. Data that has already been synced remains in both systems. You can reconnect at any time by following the Connect eSUB and QBO steps above.

Permissions

Administrators can adjust permissions; see Set Up User Permissions.

FAQ

Which editions of QuickBooks Online are supported?

QuickBooks® Online Plus and Advanced. Simple Start, Essentials, and QuickBooks® Desktop are not supported. See Supported Editions.

Does eSUB store my QuickBooks credentials?

No. The connection uses Intuit’s secure authorization flow, and your QBO credentials are never stored in eSUB. See How the Connection Works.

Why didn’t my timecards sync to QuickBooks?

Only approved timecards sync, and the sync is run on demand from Time Management rather than automatically. Approve the timecards first. See Sync Timecards to QBO and Time Management.

A record failed to sync. Where do I find out why?

Failures are recorded in the Error Log on the Integrations page, which identifies the record and the reason. Common errors and their fixes are listed there too. See Monitor Sync Errors.

What happens to my data if I disconnect?

Disconnecting stops all syncing between the two systems. See Disconnect from QBO for what is retained.