QuickBooks Online Integration

Solves the double-entry problem — the same Invoice/Payment/Bill re-keyed by hand into both CM and QuickBooks — by pushing what CM owns into a tenant's real QuickBooks Online company, on a bookkeeper's own say-so. QuickBooks stays the system of record for accounting; CM stays the front-end. Written 2026-09-02. Target: QuickBooks Online, not Desktop.

Grounded facts

Verified 2026-09-02 — against real code and Intuit's own live docs, not memory or assumption.

The schema already anticipated this — far more than expected

A full audit of every column named like a sync-tracking field turned up 14 tables with dormant tracking columns already sitting in the schema, several more than a first pass (checking only C# edit models, not the raw database) had found:

None of these old columns store a QBO SyncToken (optimistic-concurrency token) — they were shaped for the older QBXML desktop SDK, which never had this concept. A new link table is needed regardless of whether the old columns get reused.

Real structural blockers — not solved by a link table alone

Real data-access pattern (beyond OAuth), confirmed against Intuit's own .NET SDK guide

Every actual API call - not just the OAuth handshake - goes through: OAuth2RequestValidator (wraps the access token) → a ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator) with IppConfiguration.MinorVersion.Qbo set and IppConfiguration.BaseUrl.Qbo explicitly pointed at sandbox or production. Reads use QueryService<T> (e.g. new QueryService<CompanyInfo>(serviceContext).ExecuteIdsQuery("SELECT * FROM CompanyInfo")) - the same real-query mechanism the pre-write SyncToken refresh in this plan already relies on. Writes go through the SDK's DataService<T> counterpart (Add/Update) - confirm its exact signatures via the package's own XML docs before building Phase B, same technique already used for OAuth2Client.

Real Intuit OAuth2 specifics, confirmed live against developer.intuit.com

• Authorization: https://appcenter.intuit.com/connect/oauth2 (client_id/response_type=code/scope=com.intuit.quickbooks.accounting/redirect_uri/state)
• Token exchange & refresh: POST https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer (Authorization: Basic base64(client_id:client_secret))
• Revoke: POST https://developer.api.intuit.com/v2/oauth2/tokens/revoke (same auth, JSON body {"token": "..."})
• Access token: 3600s (1 hour). Refresh token: 100-day rolling expiry, plus a ~5-year hard ceiling regardless of continuous use — a previously-unknown detail.
• Official .NET SDK: Install-Package IppDotNetSdkForQuickBooksApiV3. OAuth2Client(clientId, clientSecret, redirectUrl, environment) exposes GetAuthorizationURL, GetBearerTokenAsync, RefreshTokenAsync, RevokeTokenAsync — no hand-built HTTP needed.
• Pricing tier confirmed sufficient: this whole plan is push-only (Insert-or-Update = Intuit's "Core APIs," unmetered/uncapped on every tier including the free Builder tier). "CorePlus" (metered, data-out/reporting) only matters for reads this plan doesn't do at volume — the free tier is enough.

Design decisions

One new canonical link table, not more ad-hoc columns

Given 14 tables already have inconsistent dormant columns (four different naming conventions, no SyncToken anywhere), and QBO's REST API requires a SyncToken per record that none of them track — a single new QuickBooksEntityLink table (SiteID/EntityType/LocalRecordID/QuickBooksID/SyncToken) is the source of truth for every synced entity, present and future. The old columns are left alone, unused by this feature.

CM's push always wins — no drift detection

Confirmed with the user: CM is the front-end of record, not one of two systems kept in sync. A Customer/Job edited directly in QuickBooks is not detected or reconciled, by choice. The only handling needed is purely technical: before any update push, re-read the entity from QBO to get its current SyncToken so the write doesn't fail — CM's data still overwrites regardless of what that read returns.

Never automatic — matches IRBS exactly, both directions

Every entity type gets an Include checkbox; only checked rows push when "Synchronize" is clicked. This mirrors IRBS's own dashboard precisely, where both pull (the read-only "QuickBooks Records" mirror, used for matching) and push were separate, explicit, bookkeeper-triggered button clicks — never scheduled, never silent.

Lazy token refresh, not a background service

Access tokens are checked and refreshed on demand before each API call, avoiding this codebase's first BackgroundService for something that doesn't need proactive scheduling. If the refresh token itself lapses, the connection needs re-authorization — an expected state, not an error to engineer around.

Entity & transaction plan

All 11 of IRBS's real "Integration Items," plus Customer — the foundation entity IRBS's own hierarchy rule (no Transaction without a Customer and Job) requires before anything else can sync.

Not yet phased — found in the schema audit but not part of IRBS's own push list, purpose unconfirmed: GLAccount (matches the Lists-tier "Chart of Accounts," pull-only), CheckInfo (matches "Checks," pull-only), JournalEntry/JournalEntryItem, CostAssembly, Asset, Contact.EntityGUID.

Field-level mapping, per entity

The real check for "did CM capture everything QBO needs" — not just does the entity exist, but does every field QBO requires (or that CM would want to push) have a real CM column to source it from. Gaps are called out inline, not glossed over.

Customer — CM Organization/Contact(Person)

QBO's real, full Customer field list confirmed 2026-09-02 against Intuit's own API reference (not guessed) - both tables below checked against it, in both directions.

CM → QBO — what CM already has, and where it goes:

QBO → CM — every real QBO Customer field, checked against CM's schema in the other direction. This is the direction that actually surfaces what's missing, since walking outward from CM's own fields can only ever confirm what CM already has a place for:

Net for Customer, per the "push as much as possible" strategy below: DefaultTaxCodeRef/Taxable (ties to the already-known state-tax simplification), CustomerTypeRef, and PaymentMethodRef are real, worth-closing gaps — each just needs one new CM column/lookup, not a redesign. ResaleNum/BillWithParent/OpenBalanceDate/TaxExemptionReasonId are lower-value (resale/tax-exemption certificates, opening-balance seeding) but still cheap single-column additions if a real tenant ever asks. None of these are architecturally hard — the QBO → CM tables in this doc are the actual punch list.

Job — CM ProjectInfo, pushed as a QBO Customer with ParentRef

Vendor — CM Organization (VendorTypeID set)

Real QBO field list confirmed 2026-09-02.

CM → QBO:

QBO → CM:

Employee — CM Employee (+ linked Contact)

Real QBO field list confirmed against Intuit's live docs, 2026-09-02. Better finding than a first pass assumed: Employee.ContactID links to a real Contact row with NamePrefix/MiddleName/NameSuffix/DOB/GenderID - so the "split EmployeeName into GivenName/FamilyName" problem mostly isn't real work, it's reading the already-linked Contact record instead of parsing a string.

CM → QBO:

QBO → CM:

Invoice — CM Invoice + InvoiceItem

Real QBO field list confirmed 2026-09-02 (a genuinely long one - Invoice is QBO's richest transaction entity).

CM → QBO:

QBO → CM:

Payment — CM PaymentReceipt

Real QBO field list confirmed 2026-09-02 - a short one, Payment is a simple entity.

CM → QBO:

QBO → CM:

Bill — CM Bill + BillItem

Real QBO field list confirmed 2026-09-02. Resolves the "unverified" flag from Phase D: a direct SQL check confirms BillItem (BillItemID/BillID/ItemID/Qty/UnitPrice/LineTotalAmount/SourcePOItemID) is real - item-based, cleanly matching QBO's ItemBasedExpenseLineDetail. A real Ref_BillableStatus lookup table also exists, matching QBO's own BillableStatus line concept almost exactly.

CM → QBO:

QBO → CM:

Time Tracking — CM TimeRecord

Real QBO field list confirmed 2026-09-02.

CM → QBO:

QBO → CM:

Estimate — deliberately not detailed here

Phase F. QBO's Estimate is a flat priced-line list; CM's ProjectEstimate is a Category/Item cost hierarchy with per-category markup QBO never sees. A field-by-field table would be premature before the flatten strategy itself is designed — that's the actual work of Phase F, not a mapping exercise like the entities above.

Reference lists — QBO "Lists" vs. CM's Ref_* tables

Every *Ref field across the entity tables above (SalesTermRef, PaymentMethodRef, ClassRef, DepartmentRef, APAccountRef, ItemRef...) points at one of QBO's own Lists resources. Since SiteID=1 is CM's core/default tenant (every other SiteID reads core+its own additions), seeding SiteID=1's Ref_* tables with QBO's real standard values means any tenant who later connects QBO starts from an already-compatible list, not an empty one.

Phasing

Verification approach

• Phase A: a real OAuth round-trip against the user's own Intuit sandbox company — the one piece that can't be verified by backend checks alone.
• Phase B: direct SQL cross-check of QuickBooksEntityLink after each Synchronize, plus visual confirmation in the sandbox company's own QBO web UI that the pushed Customer/Job actually appears correctly — not just a 200 response. Edit the same record locally, re-sync, confirm it updates the same QBO record rather than duplicating it.
• Phase C (code-level, done): RBAC gating live-verified on all three pages (Setup/Item Mapping/Sync). The Invoice-candidates join logic verified directly against real data — a real test Project's Job link was temporarily inserted by hand, confirmed its 3 real Invoices (with fully-populated CostItemID line items) correctly surface as sync candidates, then the fixture was removed. Still needed once real credentials exist: map a real Item, push a real Invoice, confirm the "unmapped line" error fires correctly for an unmapped one, push a real Payment with a correct LinkedTxn, and visually confirm both appear right in the sandbox company's own QBO web UI.
• Phase D (code-level, done): same discipline — a real Vendor link (Navy Federal Credit Union, a real test-data vendor) was temporarily inserted by hand, confirmed the one real test Bill (referencing that same vendor) correctly surfaces as a sync candidate, then the fixture was removed. Still needed once real credentials exist: push a real Vendor and Bill, confirm the QBO Vendor entity (not Customer) is what actually appears in the sandbox.
• Phase E (code-level, done): same discipline — a real Employee link was temporarily inserted by hand, confirmed both of the real test TimeRecord rows (via the TimeHeader join, not UserID) correctly surface as sync candidates, then the fixture was removed. The WorkDuration→Hours/Minutes split was hand-verified against 4 sample values (6.00→6h0m, 5.00→5h0m, 7.5→7h30m, 4.25→4h15m), all exact. Still needed once real credentials exist: push a real Employee and TimeActivity, confirm it appears correctly in the sandbox as an unbilled internal time entry.
• Phase F (code-level, done): same discipline — a real Job link was temporarily inserted by hand, confirmed the real 9-line test Estimate correctly surfaces as a sync candidate with every line's ItemID populated, then the fixture was removed. The ExtPriceTotal formula itself was already proven correct against real data in Report Builder's own verification pass, not re-derived here. Still needed once real credentials exist: push a real Estimate, confirm the flattened line amounts land correctly in the sandbox and match CM's own totals.

Critical files

• StripeConnectService.cs — src/ClientManager.Data/Services/ (OAuth-connect pattern to mirror)
• StripeConnectForm.razor — src/ClientManager.Web/Components/Site/ (connect/return-page pattern)
• FranchiseDashboard.razor — src/ClientManager.Web/Components/Pages/ (the real admin-gating pattern to copy)
• QuoteToPurchaseOrderService.cs — src/ClientManager.Data/Services/ (thin orchestration Service shape)
• NavCategoryCatalog.cs — src/ClientManager.Web/Components/Layout/
• Program.cs — src/ClientManager.Web/ (OAuth callback, webhook, config, DI)
• QuickBooksSyncService.cs — src/ClientManager.Data/Services/ (Customer/Job/Item/Invoice/Payment push, all in one thin orchestration class)
• QuickBooksItemMapping.razor, QuickBooksSync.razor, QuickBooksSetup.razor — src/ClientManager.Web/Components/Pages/

Full implementation-level detail (exact method signatures, SQL, file-by-file steps) lives in the working plan file, not duplicated here — this doc is the durable reference for the research and decisions behind it.