Can QuickBooks Desktop qbXML Ingestion Run Unattended? Four Conditions, Three Primary-Source Answers, One Gap

The question

Does the QuickBooks Desktop company file need to be open, in single-user mode, on an interactive Windows session for the Web Connector to serve qbXML? Determines whether QBE ingestion can be unattended at all.

Context: this was carried as an explicitly unverified blocker in [[2026-07-19-midmarket-variance-analysis-data-inputs]], which scoped QuickBooks Enterprise as "human-export-step for v1" on the strength of vendor/secondary sources only. That scoping decision drives MAC client-tier pricing, so the assumption needed a primary source.

Both Intuit primary sources were reached this round. The QuickBooks Web Connector Programmer's Guide v2.0 and the QuickBooks SDK Programmer's Guide were downloaded from Intuit's own static.developer.intuit.com/qbSDK-current/ path and read directly. Three of the four sub-conditions are now answered from Intuit primary text. One is not, and is labelled as such.

What we already know (from the vault)

• The prior brief flagged this exact claim as unverified and it was load-bearing. [[2026-07-19-midmarket-variance-analysis-data-inputs]] closes with an explicit verification note: "QuickBooks Desktop connector operational requirements (company file open, single-user mode, interactive Windows session) ... could not be confirmed from an Intuit primary source and are carried as unverified." It nonetheless used that unverified claim to tier QuickBooks Enterprise below NetSuite and Sage Intacct on automatability.
• The qbXML report surface itself is already primary-source verified. Same brief: BudgetSummaryReportQuery exposes five report types, FiscalYear is required, BudgetCriterion takes one dimension only, and there is no ReportAccountFilter on the budget query. That constraint is unaffected by anything in this brief.
• The tiering has a dollar consequence. [[2026-04-16-client-reporting-automation-one-pager]] prices the offer at "5 standard-tier clients = $12,500/month recurring" against "5 founder-advisory clients = $37,500/month". Which tier a QuickBooks Enterprise client lands in is a ~$2,500/month/client question, so "can this be unattended" is a pricing input, not just an engineering detail.
• The architectural frame already anticipated the on-prem seam. [[2026-03-28-cfosecrets-unbundling-the-erp-tech-legacy-iv]] puts an AI-driven integration layer (Layer 3) around a shrunk ERP. QuickBooks Desktop is the case where Layer 3 cannot be pure cloud plumbing - it has a mandatory Windows footprint.

What the web says

Sub-condition (a): must the company file be open in the QuickBooks application? — NO, conditionally. PRIMARY-VERIFIED.

• QBSDK Programmer's Guide, BeginSession reference, qbFile parameter: "QuickBooks need not be running if your application has been authorized for automatic logins. Supply qbFile as NULL or an empty string if you need to access the company file currently open in QuickBooks."
• Same guide, "More Information about Login Modes": "In unattended mode (auto-login), QuickBooks runs in the background ... The ctLocalQBD type either uses the local QuickBooks currently running or, if not running, launches QB in unattended mode (without UI, thus non interactively)."
• The inverse is equally explicit: "If QuickBooks is already launched with an open company file, this value can be NULL or an empty string ... If no file is open, an error occurs."
• The Web Connector inherits this. QBWC Programmer's Guide, on the string your web service returns from authenticate: "QBWC will use that string as the path to the company file and will attempt to open it; an empty string means use the currently open company file."
• Practical rule: pass an explicit full company-file path, never an empty string, and the file does not need to be pre-opened. Pass an empty string and you have just made a human's open QuickBooks window a hard dependency. Most naive integrations pass the empty string, which is almost certainly why the secondary literature says "the file must be open."
• One hard blocker survives: QBWC error remediation for codes 1007/1008/1009 says the common causes are "that QuickBooks is not running, and you need to start it, or make sure a company file is open and no modal dialog box is open." A modal in QuickBooks (update prompt, backup nag, message of the day) blocks the request processor. That is the classic unattended-run killer.

Sub-condition (b): must it be in single-user mode? — NO. PRIMARY-VERIFIED, with an internal contradiction in Intuit's own docs.

• BeginSession takes an open-mode constant. Intuit's reference for qbFileOpenDoNotCare: "Allows either single-user or multi-user mode. If the specified company file is already open, QuickBooks allows the authentication process to proceed. If no company file is open, QuickBooks opens the company file in multi-user mode. If a different company file is already open, an error is returned."
• The QBFC equivalent omDontCare is documented differently in the same guide: "accept whatever mode is currently in effect, or single-user mode if no other mode is in effect." And an IMPORTANT box states: "If QuickBooks 2007 and later is running non hosted, SDK applications starting QuickBooks in DoNotCare mode will open QuickBooks in single-user mode." These two passages disagree on the no-file-open default. Best reconciliation: hosting mode decides - hosted/multi-user-enabled files default multi-user, non-hosted files default single-user. Treat as an empirical test, not settled doc.
• Single-user is affirmatively not required for reads. Intuit's own list "Enterprise Features Requiring Single User Mode" is backup, condense, rebuild, IIF import/export, accountant review, payroll setup, and similar. No report query appears on it. The only list-mutation rule ("to delete a list object, you must have the company file open in single-user mode") carries an explicit Enterprise carve-out: "for QuickBooks Enterprise edition, it is possible to delete list items in multi user mode."
• The danger runs the other way. "Lockout. If your application attempts to open a company file in single-user mode and that company file is already open in multi-user mode, your application will not be able to access the company data file." So requesting qbFileOpenSingleUser against a hosted client file is the failure mode, not the requirement.

Sub-condition (c): must there be an interactive/logged-in Windows session? — SPLIT. The QuickBooks process: NO, primary-verified. The Web Connector process: NOT PRIMARY-VERIFIED.

• For QuickBooks itself the answer is clean: "launches QB in unattended mode (without UI, thus non interactively)". Intuit's UAC compatibility table (Table 5-2) lists case (b) as UAC ON / mode of connection Unattended / client Elevated / QuickBooks Not Running / SDK connection Successful. UAC elevation must match between QuickBooks and the SDK client; mismatched elevation is listed as an explicit failure case.
• For the Web Connector, Intuit's primary documentation is silent on running QBWC as a Windows service or without a logged-in user. What the primary doc does establish, all of it consistent with a desktop app: QBWC is a user-launched application with a system-tray presence and a Notify QWC element controlling tray pop-ups; Auto-Run is a checkbox in the QBWC UI; "scheduled updates happen only when the web connector is running. If the user shuts down the web connector there will be no scheduled updates until the web connector is restarted by the user"; error QBWC1020 is a modal exit-confirmation dialog shown when scheduled jobs exist; and every Appendix A remediation is phrased as a human at a console ("Uncheck Auto-run, exit and re-start QB web connector").
• The only explicit statement found is secondary: Procore's QuickBooks Web Connector best-practices manual states "The Windows account used to install the connector must remain actively logged in to the workstation or server for the sync to run" (v2.support.procore.com). One integrator, not Intuit. Confidence: medium-high - it is consistent with every architectural detail in Intuit's own guide, but it is not an Intuit statement and it was not found corroborated in a second independent primary-adjacent source.
• The escape hatch that the question's framing hides: QBWC is a convenience layer, not the API. qbXML is served by QBXMLRP2, a local COM request processor. A locally-installed agent can call OpenConnection2 / BeginSession / ProcessRequest directly and never involve the Web Connector at all. Everything in (a), (b) and (d) applies to that path; the QBWC session constraint does not. Intuit does not document service-mode hosting for that either, and Windows Session 0 isolation makes out-of-process COM launching of a GUI app hostile, so this is a promising path that is untested and unblessed, not a verified one.
• A related unattended restriction is documented and worth watching: qbXML status code 3301, "Not allowed in unattended mode - Cannot perform this request unless an interactive QuickBooks user is logged in", alongside 3300 "Could not open the window or form." These attach to requests that drive the QuickBooks UI. Report queries are not documented as members of that class, but that was not affirmatively verified for BudgetSummaryReportQuery specifically.

Sub-condition (d): does admin-authorized unattended mode differ, and does hosted/multi-user change it? — YES to both. PRIMARY-VERIFIED.

• Unattended is an explicit, admin-granted, per-company-file authorization: "Authorize the application to log on in unattended mode (auto login) by selecting 'Yes, allow access even if QuickBooks is not running.'" And: "the user must be logged in as the QuickBooks administrative user in order to authorize these preferences."
• It is all-or-nothing: "Either your application gets all of its requirements or it is refused access to QuickBooks."
• The app declares its need up front via AuthPreferences, which must be set before BeginSession: PutUnattendedModePref(umpRequired) "causes the QuickBooks authorization dialog to display only the selection choices of 'No' ... or 'Yes, allow access even if QuickBooks is not running'." QBWC surfaces the same three knobs as QWC-file elements - UnattendedModePref (umpRequired/umpOptional), IsReadOnly (true/false), PersonalDataPref - each documented as informing "QBXMLRP2 (request processor)".
• Unattended runs as a named QuickBooks user: "if the user selects unattended mode authorization, and if there is more than one user ... the 'login as' dropdown is visible and enabled." That user's QuickBooks permissions bound what the integration can read, and Intuit documents a failure mode titled "What Happens if the Administrative User Deletes the Auto-Login User?"
• There is always a one-time interactive bootstrap. The authorization dialog must be clicked by the QuickBooks admin at a console, once per company file. "Unattended" means steady-state unattended, never zero-touch.
• Hosted/multi-user changes who gets locked out, and the direction is favourable: Table 5-1 shows that when an integrated application opens the file in multi-user, "QB users on same machine = no access; all other integrated applications = access; QB users on other machines = access." Confirmed in prose: "even when the integrated application opens a company file in multi-user mode, other integrated applications can access the company file, but no actual users can access that company file on the same system." Run the agent on the file-hosting server, open multi-user, and humans on workstations keep working.
• One capability is genuinely lost in unattended mode: event subscriptions. Intuit lists "QuickBooks is being run in unattended mode" among the "normal conditions in which data events are lost for your application." Unattended ingestion is polling-only by design. For a nightly close-cycle pull that is irrelevant.

Documentation currency caveat. The QBWC Programmer's Guide carries "(c) 2009 Intuit Inc." and version 2.0; the SDK Programmer's Guide carries "(c) 2013 Intuit Inc." Both are served from Intuit's own qbSDK-current path, so they are Intuit's current canonical texts, but they predate current QBWC releases and current Enterprise. Nothing found contradicts them; nothing found confirms they were revised.

Convergences and contradictions

• The secondary literature was wrong in a specific, diagnosable way, and the prior brief inherited the error. "The company file must be open" is true only if you pass an empty string to BeginSession. Intuit's primary text says the opposite when an explicit path is supplied and auto-login is authorized. Likewise "single-user mode" is not a requirement for reads and is actually the lockout risk. Two of the three conditions in the original question are false as stated, and [[2026-07-19-midmarket-variance-analysis-data-inputs]] tiered QuickBooks Enterprise partly on them.
• The one condition the secondary sources got right is the one Intuit never addresses. The Web Connector really does appear to need a live Windows session, and Intuit's docs neither assert nor deny it - they simply describe a tray application throughout. This is the correct shape for a residual unknown: the vendor documented the request processor thoroughly and the desktop wrapper's deployment envelope not at all.
• Intuit contradicts itself on the DoNotCare default. The QBXMLRP2.BeginSession reference says multi-user when no file is open; the QBFC omDontCare reference and the hosting IMPORTANT box say single-user. This is not a reading error, it is two passages in the same PDF. Any implementation must probe the live client environment rather than trust either sentence.

Synthesis for RDCO

Verdict: conditionally unattended, and the condition is a Windows host - not a human. Steady-state nightly qbXML pulls against QuickBooks Desktop Enterprise can run with no person present. The requirements are: (1) a Windows machine with QuickBooks installed, ideally the machine hosting the company file; (2) a one-time authorization click by the QuickBooks admin granting "allow access even if QuickBooks is not running," bound to a named QuickBooks login with read permissions on the GL; (3) AuthPreferences set with umpRequired and IsReadOnly(false) before BeginSession; (4) an explicit full company-file path, never an empty string; (5) qbFileOpenDoNotCare, never qbFileOpenSingleUser; and (6) a persistent logged-in Windows session for the Web Connector, or a direct-COM agent that skips the Web Connector. Condition (6) is the only one carrying real uncertainty, and it has a boring standard mitigation - an auto-logon Windows VM whose console session never terminates.

This changes the MAC tier axis from "automatable vs. not" to "client-side runtime required vs. not," which is a better axis anyway. The previous scoping put QuickBooks Enterprise in a human-export tier on the belief that unattended ingestion was technically impossible. It is not impossible. What is true is that Sage Intacct and NetSuite can be served entirely from RDCO-controlled cloud infrastructure with a credential, while QuickBooks Enterprise requires software running inside the client's environment that RDCO must specify, install, monitor, and troubleshoot remotely. That is a genuine cost and a genuine support-surface expansion, and it should be priced. But it is a commercial choice about where RDCO wants its operational boundary, not a technical wall. Against [[2026-04-16-client-reporting-automation-one-pager]]'s $2,500/month standard tier, a QuickBooks Enterprise client should carry either a setup fee covering the connector build and the VM, or a tier premium covering the ongoing failure surface - and the honest sales line is "we can automate this, and it needs a small always-on Windows box in your environment," not "QuickBooks clients export manually."

The failure modes are operational, not architectural, and they are the thing to design against. A modal dialog in QuickBooks blocks the request processor outright, per Intuit's own error remediation, which means an unattended run dies silently on an update prompt or a message-of-the-day. The auto-login user can be deleted by a QuickBooks admin who has no idea it is load-bearing. UAC elevation must match between QuickBooks and the calling process or the connection fails. A file-mode collision produces lockout rather than a graceful degrade. None of these is exotic; all of them are the reason the integrator community's folklore says "it needs someone watching." The engineering answer is a health-check ping per run, alerting on missed runs rather than on failed runs, and a documented client-side runbook - which is exactly the kind of artifact [[2026-05-13-fde-wave-convergence-rdco-thesis]] argues RDCO should be extracting and productizing anyway.

One deliberate scope note: none of this improves the shape of the data. The prior brief's harder finding stands unchanged - BudgetSummaryReportQuery returns a presentation grid whose hierarchy must be inferred from rowType and subtotal placement, and it has no account filter. Unattended access gets the grid arriving on a schedule; it does not make the grid a data frame. The canonical intermediate schema proposed in [[2026-07-19-midmarket-variance-analysis-data-inputs]] remains the load-bearing build, and the QuickBooks adapter remains the ugliest of the three regardless of how it is triggered.

Why this is in the vault

This brief retracts a specific unverified claim that was already priced into a scoping decision: [[2026-07-19-midmarket-variance-analysis-data-inputs]] tiered QuickBooks Enterprise as "human-export-step for v1" on the belief that unattended qbXML ingestion was impossible, and Intuit's own SDK and Web Connector programmer's guides show that two of the three asserted blockers (file must be open, must be single-user) are false as stated. The MAC client-tier split and the per-client pricing in [[2026-04-16-client-reporting-automation-one-pager]] should be re-cut on "does this client need an RDCO-managed Windows host" rather than on "can this client be automated at all."

Open follow-ups

• Empirically test whether the QBWC scheduler continues to fire under a locked, disconnected-RDP, and signed-out Windows session. This is the one sub-condition no primary source answers and it is the whole remaining risk.
• Can QBXMLRP2 be driven from a Windows service in Session 0 with QuickBooks not running, given UAC elevation matching? If yes, the Web Connector is optional and the session constraint disappears entirely. Session 0 isolation makes this non-obvious.
• Does BudgetSummaryReportQuery (or any qbXML report query) ever return status 3301, "Not allowed in unattended mode"? Verify against a live auto-login session before promising an unattended report pull.
• Do current QBWC releases differ from the 2009 v2.0 Programmer's Guide on unattended behaviour or service support? Intuit serves the 2009 doc from qbSDK-current, which may mean unchanged or may mean unmaintained.
• Is there a supported way to suppress QuickBooks modal dialogs (update prompts, message of the day, backup reminders) so an unattended run cannot be blocked by one? This is the highest-frequency real-world failure.
• Which default does qbFileOpenDoNotCare actually produce when no file is open - Intuit's two passages disagree, and hosted vs. non-hosted appears to be the discriminator. Probe on a hosted Enterprise file.
• Do hosted-QuickBooks providers (Right Networks and peers) permit installing a custom connector or agent inside the hosted environment? For clients on hosted Enterprise this is a commercial gate that no amount of SDK capability resolves.

Related

• [[2026-07-19-midmarket-variance-analysis-data-inputs]] — the parent brief; this one retracts its unverified QuickBooks connector assumptions
• [[2026-04-16-client-reporting-automation-one-pager]] — the tier pricing this verdict re-cuts
• [[2026-04-30-mac-bet-architecture-audit]] — MAC bet architecture and the productize-client-reporting workstream
• [[2026-03-28-cfosecrets-unbundling-the-erp-tech-legacy-iv]] — the Layer 3 integration-layer frame this sits inside
• [[variance-analysis-ticket]] — the shipped brigade skill downstream of any QuickBooks adapter
• [[2026-05-13-fde-wave-convergence-rdco-thesis]] — the runbook-as-artifact argument for productizing the client-side connector setup

Sources

Vault

• ~/rdco-vault/06-reference/research/2026-07-19-midmarket-variance-analysis-data-inputs.md
• ~/rdco-vault/01-projects/services-offering/2026-04-16-client-reporting-automation-one-pager.md
• ~/rdco-vault/06-reference/2026-04-30-mac-bet-architecture-audit.md
• ~/rdco-vault/06-reference/2026-03-28-cfosecrets-unbundling-the-erp-tech-legacy-iv.md
• ~/rdco-vault/06-reference/2026-05-13-fde-wave-convergence-rdco-thesis.md

Web — PRIMARY (Intuit)

• Intuit QuickBooks SDK — QuickBooks Web Connector Programmer's Guide v2.0 (Intuit, (c) 2009): https://static.developer.intuit.com/qbSDK-current/doc/pdf/QBWC_proguide.pdf — QWC file element reference (UnattendedModePref, IsReadOnly, PersonalDataPref, Scheduler, Notify); authenticate company-file-path semantics; Appendix A error codes QBWC1007/1008/1009/1020/1032.
• Intuit QuickBooks SDK — QuickBooks SDK Programmer's Guide (Intuit, (c) 2013): https://static.developer.intuit.com/qbSDK-current/doc/pdf/QBSDK_ProGuide.pdf — Ch. 4 "Specifying Authorization Preferences" (PutUnattendedModePref, admin-only authorization dialog, login-as dropdown); Ch. 5 "More Information about Login Modes", "Single-User vs. Multi-User Mode", Table 5-1 access rights, Table 5-2 UAC cases; BeginSession / QBSessionManager.BeginSession reference including qbFileOpenSingleUser / qbFileOpen / qbFileOpenDoNotCare and omSingleUser / omMultiUser / omDontCare; qbXML status codes 3162, 3300, 3301; "Enterprise Features Requiring Single User Mode"; lost-events conditions.
• Intuit Developer — Get started with QuickBooks Web Connector: https://developer.intuit.com/app/developer/qbdesktop/docs/get-started/get-started-with-quickbooks-web-connector — fetch returned truncated content; not usable as evidence this round.

Web — SECONDARY (labelled)

• Procore — QuickBooks Web Connector Best Practices: https://v2.support.procore.com/product-manuals/quickbooks-desktop/qwc-best-practices — sole explicit statement found that the installing Windows account "must remain actively logged in to the workstation or server for the sync to run." Integrator documentation, not Intuit.
• Conductor — QuickBooks Web Connector Guide: https://conductor.is/blog/quickbooks-web-connector-guide — third-party overview, not relied on for any claim above.
• Apideck — Building an integration with the QuickBooks Desktop API: https://www.apideck.com/blog/build-an-integration-with-quickbooks-desktop-in-2025 — third-party overview, not relied on for any claim above.

Verification status by sub-condition