QuickBooks Online Integration — Implementation & Support Guide

Table of Contents

1. [What This Integration Does](#1-what-this-integration-does)
2. [Before You Begin](#2-before-you-begin)
3. [Connecting QuickBooks Online](#3-connecting-quickbooks-online)
4. [Entity Mapping](#4-entity-mapping)
5. [Invoice Export](#5-invoice-export)
6. [Bill Export](#6-bill-export)
7. [Payment Synchronization](#7-payment-synchronization)
8. [Invoice Voiding](#8-invoice-voiding)
9. [The Daily Sync](#9-the-daily-sync)
10. [Troubleshooting Guide](#10-troubleshooting-guide)
11. [Implementation Checklist](#11-implementation-checklist)
12. [Quick Reference](#12-quick-reference)

 

1. What This Integration Does

The QuickBooks Online (QBO) integration creates an automated, two-way link between the VIP platform and a vendor's QuickBooks Online company file. Once configured, it runs on a scheduled basis (typically every 5–15 minutes) with no manual intervention required.

What Gets Synchronized

Direction	What	When
VIP → QBO	Invoices (normal & supplement)	When an invoice reaches an eligible status
VIP → QBO	Bills (adjuster & salesman compensation)	Same trigger as invoices (if bill export is enabled)
VIP → QBO	Payment records	When a VIP invoice is marked "Payment Received"
QBO → VIP	Payment status	When a payment is recorded against an invoice in QBO
QBO → VIP	Voided invoices	When an invoice is voided in QBO

 

What It Is Not

• Not real-time. The sync runs on a schedule. There will always be a short lag (typically under 15 minutes) between an action in VIP and it appearing in QBO, or vice versa.
• Not a full accounting sync. Only invoices, bills, and payments are synchronized. Journal entries, expenses, payroll, and other QBO data are not touched.
• Not automatic on day one. The integration requires an initial setup and mapping session before it will begin exporting data.

 

2. Before You Begin

The following must be in place before configuring the integration for a vendor.

On the QuickBooks Side

Requirement	Notes
Active QuickBooks Online subscription	Any paid QBO plan. QBO Simple Start does not support all features (e.g., Class Tracking). QBO Plus or Advanced is recommended.
An Intuit Developer App	A registered OAuth 2.0 app at developer.intuit.com associated with the vendor's QBO account. VIP Engineering provides the Client ID and Client Secret.
Class Tracking enabled	Required. Go to QBO → Settings → Account and Settings → Advanced → Categories → enable Track classes. Every invoice line item is tagged with a class representing the insured's state for regional reporting.
Custom fields configured	Three custom fields must exist in QBO on the Invoice form, in this exact order: Claim Number (field 1), Insured Name (field 2), Inside Adjuster (field 3). These are populated automatically on every exported invoice.
Vendors, Customers, Products/Services, and Bank accounts set up	These QBO entities need to exist before mapping can be completed. The integration imports them automatically (see The Daily Sync), but they must first exist in QBO.

 

On the VIP Side

Requirement	Notes
Carrier companies configured	All carriers to be synced must exist in VIP with correct billing addresses and email addresses.
Adjusters and salesmen configured	All independent adjusters and salesmen who will receive compensation bills must be set up as VIP users.
Line items, UOM, and flat fees configured	All invoice line item types (assignments, unit of measure items, flat fees) must be configured in VIP before mapping.
IsLicensed flag set correctly per carrier	This flag controls when invoices are exported. See Invoice Export. Confirm with the vendor which carriers are licensed.

 

 

3. Connecting QuickBooks Online

The connection between VIP and QBO is secured with OAuth 2.0. This authorization must be completed through the VIP Admin UI — it cannot be done via any other method.

Initial Authorization

1. Log in to Invision as an Admin.
2. Navigate to Admin → QuickBooks Mapping.
3. On the configuration tab, enter the Client ID and Client Secret provided for this vendor's QBO app.
4. Click Connect to QuickBooks. You will be redirected to the Intuit login page.
5. Log in with the QBO account credentials and click Authorize.
6. You will be redirected back to VIP. The connection status should show as active.

❗ Important

The person completing this step must have access to the QBO company file. Have the vendor's QuickBooks administrator present during initial setup.

How Tokens Work

After authorization, VIP stores an access token (short-lived) and a refresh token (long-lived). The integration automatically renews the access token before each run — no manual action is needed for routine token refresh.

Token	Lifespan	Renewed By
Access Token	~55 minutes	Automatically by the sync process
Refresh Token	~100 days	Manually — requires re-authorization through the Admin UI

 

⚠️ Warning

If the refresh token expires (after approximately 100 days of no sync activity) or is revoked by the vendor (e.g., they changed their QBO password or revoked app access), the integration will stop working silently. Re-authorization through Admin → QuickBooks Mapping is required. Set a reminder to check quarterly if a vendor's sync volume is low.

Sandbox vs. Production

The integration supports both a sandbox (test) QBO environment and the live production environment. If a vendor needs testing in a QBO sandbox first, confirm with VIP Engineering that the correct environment is configured. Do not run production invoices against a sandbox.

 

4. Entity Mapping

Mapping is the process of telling VIP which QBO entity corresponds to each VIP entity. This is the most critical setup step. The integration will not export anything until all required mappings are complete.

Mapping is managed at Admin → QuickBooks Mapping, across five tabs.

 

Tab 1 — Company Mapping (Carriers → QBO Customers)

Purpose: Links each VIP carrier to its corresponding QBO Customer record, and associates a bank account, payment terms, salesman vendor, and expense account.

VIP Entity	Maps To	Required?	Notes
Carrier	QBO Customer	Yes	Invoices are issued to this customer in QBO
—	QBO Bank Account	Yes	Where payment deposits are recorded
—	QBO Salesman Vendor	If salesman bills enabled	The QBO vendor used for salesman compensation bills
—	QBO Payment Terms	Recommended	Defaults to "Net 30" if not set
—	QBO Expense Account	If bills enabled	The GL account debited on adjuster/salesman bills

 

"Apply All" shortcut: A single QBO Customer, Bank, Salesman, Term, or Account can be applied to all carriers at once. Useful when one vendor works with many carriers under the same QBO customer.

📋 Note

If a carrier does not have a mapped QBO Customer, all invoices for that carrier will be skipped until the mapping is added.

 

Tab 2 — Vendor Mapping (Adjusters → QBO Vendors)

Purpose: Links each VIP adjuster (independent contractor) to a QBO Vendor. This mapping is only required if Bill Export is enabled.

VIP Entity	Maps To	Notes
Independent Adjuster	QBO Vendor	Bills for this adjuster's compensation are posted to this QBO vendor

 

"Apply All" shortcut: Applies one QBO vendor to all adjusters. Only appropriate in single-adjuster scenarios.

📋 Note

If an adjuster does not have a QBO Vendor mapping and bill export is enabled, that adjuster's compensation bill will be skipped for every invoice they appear on.

 

Tab 3 — Assignment Mapping (Line Items → QBO Products & Services)

Purpose: Links VIP assignment types (the primary service performed) to QBO Products & Services. Supports separate mappings for Normal and Supplement invoices via a toggle.

VIP Entity	Maps To	Notes
Assignment / Line Item	QBO Product or Service	Appears as a line item on the QBO invoice

 

Set the toggle to Normal to map standard invoice line items, and Supplement to map supplement-specific line items. These can map to the same or different QBO items.

"Apply All" shortcut: Applies one QBO Product/Service to all line items. Use with caution — it removes granularity in QBO reporting.

 

Tab 4 — Unit of Measure Mapping (UOM → QBO Products & Services)

Purpose: Links VIP Unit of Measure charge types to QBO Products & Services. UOM charges are quantity-based (e.g., per-page, per-photo). Also supports Normal/Supplement toggle.

The amount exported is calculated as: (Quantity Used − Free Units) × Fee Per Unit, capped at the configured maximum.

 

Tab 5 — Flat Fee Mapping (Flat Fees → QBO Products & Services)

Purpose: Links VIP flat fee charge types to QBO Products & Services. Flat fees are fixed-amount additions or deductions on an invoice. Also supports Normal/Supplement toggle.

💡 Tip

A flat fee configured as a deduction in VIP will appear as a negative line item in QBO.

 

Mapping Priority

If a specific invoice has a QBO service assigned directly at the invoice level, that takes precedence over the mapping tab configuration. This allows one-off overrides without changing the global mapping.

If neither an invoice-level assignment nor a mapping tab entry exists for a line item type, that line item is skipped and the invoice is flagged with an error.

❗ Important

Complete all five mapping tabs before going live. Partial mappings are the single most common cause of export failures. Use the troubleshooting steps in [Section 10](#10-troubleshooting-guide) if invoices stop exporting after mapping changes.

 

5. Invoice Export

When Does an Invoice Export?

The integration checks for eligible invoices on every scheduled run. An invoice is eligible when:

1. It has not already been exported to QBO
2. It has no prior export error (errored invoices are held until the error is resolved)
3. Its status matches the export trigger for that carrier (see below)

The Licensed vs. Unlicensed Rule

This is a critical business rule that varies by carrier. The carrier's Licensed setting in VIP determines at which point in the workflow its invoices are sent to QBO.

Carrier Type	Invoice Exported When...	Rationale
Licensed	Invoice reaches Ready for Payment, Paid, or Paid from QB status	Licensed carriers require a higher confidence that the claim is complete before invoicing
Unlicensed	Invoice reaches Submitted — Awaiting Payment status	Unlicensed carriers receive invoices earlier in the workflow

 

❗ Important

This same rule applies to supplement invoices and to bills. Verify the IsLicensed setting for each carrier during onboarding. An incorrect setting will cause invoices to export too early or not at all.

What Appears on the QBO Invoice

Each exported VIP invoice creates one QBO Invoice with the following data:

QBO Invoice Field	Source
Customer	Mapped QBO Customer (from Company Mapping tab)
Invoice Number (Doc Number)	VIP Invoice Number
Transaction Date	Based on invoice status: date paid, date ready for payment, or submission date
Payment Terms	"Net 30" (fixed)
Billing Address	Carrier's billing address from VIP
Billing Email	Carrier's email from VIP
Currency	USD
Custom Field: Claim Number	Claim number from VIP
Custom Field: Insured Name	Insured name from VIP
Custom Field: Inside Adjuster	Claim representative from VIP
Line Items	See below
Class (per line item)	Insured's state — used for regional reporting in QBO

 

Line Items on the QBO Invoice

An invoice can carry multiple line item types. All are exported if the relevant data and mappings exist.

Line Item Type	Description
Field Fee	The primary service charge. Mutually exclusive with Percentage Fee.
Percentage Fee	Percentage-based alternative to the field fee.
Flat Fees	Fixed-amount additions or deductions. A flat fee marked as a deduction appears as a negative line.
Unit of Measure Charges	Quantity-based charges (e.g., per page, per photo) calculated against free units and caps.
Additional Expenses	Variable expense line items. QBO will auto-create an "Additional Expenses" product if it doesn't exist.
Fee Deductions	Fixed deduction lines. QBO will auto-create a "Fee Deduction" product if it doesn't exist.
Taxes	Tax charges, if tax export is enabled for this vendor. QBO will auto-create a "Taxes" product if it doesn't exist.
SLA Performance Metrics	Bonus or penalty adjustments based on performance metrics. Appears as positive (bonus) or negative (penalty).

 

Normal vs. Supplement Invoices

Both are exported by the same process. Supplement invoices use supplement-specific mappings (configured on the Assignment, UOM, and Flat Fee tabs with the Supplement toggle active) and are tracked separately in VIP, but appear as standard invoices in QBO.

Batch Size

The integration processes a maximum of 50 invoices per carrier per run. If a carrier has a large backlog, it will be cleared across multiple consecutive runs.

 

6. Bill Export

Overview

Bill export is an optional feature that creates QBO Bills (accounts payable) to track compensation owed to independent adjusters and salesmen. It must be explicitly enabled per vendor in the integration configuration.

Bills are created at the same time as their corresponding invoices — they follow the same Licensed/Unlicensed export trigger rule.

📋 Note

If bill export is disabled for a vendor, invoices will still export normally. Bills are purely additive.

Adjuster Bills

For each adjuster linked to a compensable invoice:

• A separate QBO Bill is created for that adjuster
• The bill is posted to the QBO Vendor mapped in the Vendor Mapping tab
• The expense is applied to the carrier's mapped GL expense account
• The bill amount is the adjuster's net compensation — their total compensation minus any "First Deduction" amounts (platform fees or licensing charges withheld before the adjuster is paid)
• Bills are marked as Not Billable in QBO (they are internal expense records, not charges to the carrier)

Salesman Bills

A separate QBO Bill is created for the salesman associated with the invoice, posted to the "Admin" expense account.

Class Tracking on Bills

Like invoices, every bill line item is tagged with the insured's state as a QBO Class for regional reporting.

 

7. Payment Synchronization

Payment sync is bi-directional and runs automatically on every scheduled cycle.

VIP → QBO: Pushing Payments

Trigger: An invoice in VIP is marked Payment Received with a check number and check date.

What happens:

1. The integration creates a QBO Payment record linked to the corresponding QBO Invoice
2. The payment is recorded as a Check payment type
3. The deposit is recorded to the carrier's mapped QBO Bank Account
4. The check number and check date from VIP are used as the QBO payment reference

📋 Note

Payments are always recorded as "Check" type in QBO regardless of the actual payment method used. This is a current system limitation.

QBO → VIP: Pulling Payments

Trigger: A payment is recorded against a QBO Invoice directly in QuickBooks.

What happens:

1. The integration polls QBO for any new payments since the last run
2. If a QBO payment is linked to an invoice that exists in VIP, the VIP invoice status is updated to Paid from QB
3. A payment detail record is created in VIP (check number, date, amount)
4. An audit note is added to the invoice: "Marked Payment Received from QuickBook."

First-time sync behavior: On the first run after connection, the integration looks back 30 days for existing QBO payments to catch any that were recorded before the integration was activated.

Checkpoint system: The integration tracks the last processed QBO Payment ID. Each run only processes payments newer than the last checkpoint, preventing duplicate processing. If payments appear to be missing, check whether the checkpoint ID in the vendor's QBO configuration is set correctly.

 

8. Invoice Voiding

Void status is synchronized in both directions.

Void in QBO → Updates VIP

When an invoice is manually voided in QBO, the integration detects it and marks the corresponding VIP invoice as Void. A void invoice number is generated and an audit trail entry is created.

This applies to both normal invoices and supplement invoices.

Void in VIP → Updates QBO

When an invoice is voided in VIP, the integration sends the void to QBO by zeroing out all line item amounts and quantities and marking the invoice with a void note. The original QBO Invoice record is preserved (not deleted) for audit purposes.

 

9. The Daily Sync

Once per day, the integration refreshes its local copy of QBO entity data — Vendors, Customers, Products & Services, Bank Accounts, and Chart of Accounts. This is what populates the dropdown lists in the mapping tabs.

Why This Matters for Support

• New QBO entities (Vendors, Customers, Products) will not appear in mapping dropdowns until the next daily sync. If a vendor adds a new customer or vendor in QBO today, it will be available for mapping tomorrow at the earliest.
• The sync runs at most once per day. Running the integration multiple times in a day does not trigger additional entity refreshes.
• Existing entities are never removed or modified by the sync. Only new entities are added.

🔶 Caution

The daily sync imports a maximum of 1,000 records per entity type (1,000 vendors, 1,000 customers, etc.). For vendors with very large QBO accounts, some entities may not appear in the mapping dropdowns. Contact VIP Engineering if a QBO account is expected to exceed these limits.

 

10. Troubleshooting Guide

Invoices Not Exporting

Symptom: Invoices exist in VIP but are not appearing in QBO.

Check	How to Verify	Resolution
Invoice status	Is the invoice at the correct status for its carrier type? Licensed carriers need Ready for Payment, Paid, or Paid from QB. Unlicensed need Submitted — Awaiting Payment.	Move the invoice to the correct status, or verify the carrier's Licensed setting
Prior export error	Has this invoice been flagged with a QBO error from a previous attempt?	Clear the error flag (requires Engineering support) and correct the underlying mapping issue
Missing mapping	Is every line item type on the invoice mapped to a QBO Product/Service?	Complete the mapping for the missing item type in Admin → QuickBooks Mapping
Carrier not mapped	Does the invoice's carrier have a QBO Customer assigned?	Add the carrier mapping on Tab 1 (Company Mapping)

 

 

A Specific Invoice Is Stuck / Shows an Error

Symptom: Most invoices export fine, but one (or a few) are not going through.

1. Check whether the invoice has any unusual line items that may not be mapped — compare its line items against others in the same carrier that are exporting successfully.
2. Look for a QBO error message on the invoice record in VIP (visible to Engineering via the integration logs).
3. Common causes:

• A line item type present on this invoice but absent on others (e.g., an SLA adjustment or a rarely-used flat fee type)
• A missing QBO class for a state not previously seen (e.g., a new state for insured properties)
• A duplicate invoice number — VIP invoice numbers must be unique in QBO. If a number already exists in QBO (from manual entry), the export will fail.

 

Payments Not Syncing from QBO to VIP

Symptom: A payment was recorded in QBO but the VIP invoice has not updated to Paid.

1. Confirm the QBO payment is linked to a QBO Invoice (not a standalone payment). The sync only processes payments that have an invoice association in QBO.
2. Confirm the QBO Invoice ID on the payment matches an invoice that was originally exported from VIP (payments linked to manually-created QBO invoices will not be recognized).
3. Allow one full sync cycle (up to 15 minutes) after the QBO payment is recorded.
4. If the issue persists, escalate to Engineering to check the payment checkpoint and integration logs.

 

Token / Authorization Errors

Symptom: All exports stop suddenly. Engineering reports an authentication error in the logs.

Scenario	Cause	Resolution
Access token expired	Normal — the sync usually handles this automatically	Wait for the next run; if persistent, re-authorize
Refresh token expired	Happens after ~100 days of no sync, or if QBO credentials changed	Re-authorize in Admin → QuickBooks Mapping
Refresh token revoked	Vendor changed their QBO password, revoked the app, or disconnected VIP in QBO settings	Re-authorize; vendor may need to re-grant access in their QBO Connected Apps

 

 

"Duplicate Invoice Number" Error (400 Bad Request)

Symptom: An invoice fails to export with a duplicate number error.

Cause: The VIP invoice number already exists as a QBO Invoice Document Number — either from a previous partial run or from a manually-created invoice in QBO.

Resolution options:

1. If the QBO invoice was created manually and matches the VIP invoice, delete the manual QBO invoice and allow VIP to re-export.
2. If a previous VIP export partially succeeded (invoice created in QBO but VIP was not updated), Engineering can manually record the QBO Invoice ID against the VIP invoice to mark it as successfully exported.

 

New QBO Vendor/Customer Not Appearing in Mapping Dropdowns

Symptom: A new vendor or customer was added in QBO but does not appear in the VIP mapping page.

Cause: The daily sync has not yet run since the QBO entity was created.

Resolution: Wait until the next day for the automatic sync, or ask VIP Engineering to trigger a manual entity refresh.

 

Bills Not Exporting

Symptom: Invoices are exporting to QBO but no corresponding bills are being created.

1. Confirm that Bill Export is enabled for this vendor in the integration configuration (requires Engineering access).
2. Confirm the adjuster(s) on the invoice have QBO Vendor mappings (Tab 2 — Vendor Mapping).
3. Confirm a QBO Expense Account is mapped for the carrier (Tab 1 — Company Mapping).
4. Confirm the invoice has compensation fee data (invoices without compensation lines will not produce bills).

 

11. Implementation Checklist

Use this checklist for every new QBO integration setup.

Phase 1 — QBO Preparation (Vendor completes)

• ☐ QBO subscription is active (Plus or Advanced recommended)
• ☐ Class Tracking is enabled in QBO → Settings → Account and Settings → Advanced
• ☐ Three invoice custom fields created in QBO in order: Claim Number, Insured Name, Inside Adjuster
• ☐ All Customers (carriers) exist in QBO
• ☐ All Vendors (adjusters, salesmen) exist in QBO
• ☐ All Products & Services (for invoice line items) exist in QBO
• ☐ Bank account(s) for payment deposits exist in QBO
• ☐ GL expense accounts for adjuster/salesman bills exist in QBO

Phase 2 — VIP Configuration (Implementation Specialist completes)

• ☐ IsLicensed flag verified for each carrier — confirm with vendor
• ☐ Integration authorized via Admin → QuickBooks Mapping (OAuth completed)
• ☐ Verify authorization is active and connection status shows connected

Phase 3 — Entity Mapping (Implementation Specialist completes)

• ☐ Tab 1: All carriers mapped to QBO Customers, Banks, Terms, and Expense Accounts
• ☐ Tab 2: All adjusters mapped to QBO Vendors (if bill export enabled)
• ☐ Tab 3 (Normal): All assignment types mapped to QBO Products/Services
• ☐ Tab 3 (Supplement): All supplement assignment types mapped
• ☐ Tab 4 (Normal): All UOM types mapped to QBO Products/Services
• ☐ Tab 4 (Supplement): All supplement UOM types mapped
• ☐ Tab 5 (Normal): All flat fee types mapped to QBO Products/Services
• ☐ Tab 5 (Supplement): All supplement flat fee types mapped

Phase 4 — Validation

• ☐ Trigger a test invoice through the workflow and confirm it appears in QBO
• ☐ Verify line items, amounts, custom fields, and class tracking on the QBO invoice
• ☐ If bill export enabled: confirm corresponding bill appears in QBO
• ☐ Record a test payment in QBO and confirm VIP invoice updates to Paid from QB
• ☐ Confirm authorization reminder is calendared (~90 days out for refresh token)

 

12. Quick Reference

Export Trigger by Carrier Type

Carrier Setting	Invoice Exports At
Licensed	Ready for Payment, Paid, or Paid from QB
Unlicensed	Submitted — Awaiting Payment

 

Same rule applies to supplement invoices and bills.

What Each Mapping Tab Controls

Tab	Maps	Required For
1 — Company	Carriers → QBO Customers, Banks, Terms, Accounts	Invoice export, payment sync, bill expense account
2 — Vendors	Adjusters → QBO Vendors	Bill export only
3 — Assignments	Line items → QBO Products/Services	Invoice line items
4 — UOM	Unit of measure types → QBO Products/Services	UOM invoice lines
5 — Flat Fees	Flat fee types → QBO Products/Services	Flat fee invoice lines

 

Common Error → Cause → Fix

Symptom	Most Likely Cause	Fix
Invoice not exporting	Wrong status for carrier type, or missing mapping	Check status and complete all mapping tabs
Specific invoice stuck	Unmapped line item type unique to that invoice	Identify the unusual line item and add its mapping
Payment not syncing QBO → VIP	QBO payment not linked to a QBO Invoice	Ensure payment in QBO is applied to the invoice, not standalone
All exports stopped	Refresh token expired or revoked	Re-authorize in Admin → QuickBooks Mapping
400 Duplicate Number error	Invoice number already in QBO	Delete duplicate in QBO or have Engineering reconcile the record
New QBO entity missing from dropdown	Daily sync hasn't run yet	Wait until next day or request manual refresh from Engineering
Bills not exporting	Bill export not enabled, or missing vendor/account mapping	Verify bill export setting and complete Tabs 1 and 2

 

Key Timings

Item	Value
Sync frequency	Every 5–15 minutes (configured per environment)
Invoice batch size	50 per carrier per run
Access token lifespan	~55 minutes (auto-renewed)
Refresh token lifespan	~100 days (requires manual re-authorization)
Daily entity sync	Once per day, up to 1,000 records per entity type
First-time payment lookback	30 days