QBO Launch Validation

End-to-end deposit walkthrough · ProMount by Vancomm (promount entity) · Check each box as you go

⚡ Run this first — green = ready (read-only, creates nothing; reports PASS / FAIL / MANUAL per prerequisite): doppler run -p vancomm -c dev_vancomm -- node scripts/qbo-launch-preflight.mjs

Before you start — all of these must be live (the list below is what the preflight checks & how to fix each): Bridge Worker: scoro-qbo-bridge.vancomm.workers.dev Test amounts: keep totals $5–$10. Real money flows through QBO Payments. Deposit = quote sum × prepayment_percent (e.g. $1.00 × 50% = $0.50).
See a finished example: Project 3031 · Company 565 · Quote 3290 · Prepayment 128 · Final invoice 2348
1 Create Project
manual
Do New Project in Scoro (promount entity) — clearly test-flagged name, e.g. WALKTHROUGH TEST [date]. Note the project ID.
  • Project exists with a numeric ID
  • URL contains promount
2 Create Customer
manual
Do New Company + linked Person — test-flagged name, e.g. WALKTEST CUSTOMER LLC [date]. Use a real email address (QBO will email the deposit invoice here). Note the company contact ID.
  • Company + Person saved, both linked
  • Email address is reachable
3 Create Quote
manual
Do From inside the Project, create a Quote linked to the Customer. Add a line item, keep total $5–$10. Optionally add a 5% discount. Note the total.
  • Quote exists with a quote number and total
  • Linked to correct Project and Customer
  • PDF preview renders correctly
4 Create Prepayment
manual + auto Worker Path A
Do From the Quote / Order → New prepayment invoice → set advance = 50% → Save.
Auto (Path A, ~60s): Worker mints QBO deposit invoice (50% of order total) → fetches Intuit pay-link → writes <a href>Pay online</a> into c_qbo_invoice_link on the Scoro prepayment.
Wait ~60s before sending the PDF — the pay-link populates after the Worker runs. Also confirm the PDF shows a clickable link, not raw HTML (Caveat A & B).
  • Prepayment exists; note its ID
  • Scoro: c_qbo_invoice_link is populated (not empty)
  • Prepayment PDF: "Pay online" is a live hyperlink
  • QBO: deposit invoice for test customer, amount = 50% of total, payment enabled
5 Customer Pays Deposit
manual + auto Worker Path B
Do Click the Pay online link from the prepayment PDF and pay. Or: open the QBO deposit invoice → Receive payment → enter deposit amount → Save.
Auto (Path B, ~60s): QBO payment.create webhook → Worker verifies HMAC → resolves qbomap KV entry → posts receipt to Scoro → prepayment flips to paid/reconciled.
  • QBO: deposit invoice status Paid, $0.00 balance
  • Scoro: prepayment status paid/reconciled
  • Scoro: receipt linked to the prepayment
6 Final Invoice
manual status advance + auto Worker Path C
Do Find the Order in Scoro. Advance status to Ready to Invoice (or the configured equivalent from P-3).
Auto (Path C, ~60s): Order trigger → Worker reads order + prepayment → creates Scoro final invoice → applies deposit credit (balance = order total − deposit) → creates QBO balance invoice → writes pay-link to c_qbo_invoice_link on the final invoice.
  • Scoro: final invoice exists; deposit credited; balance = order total − deposit
  • Scoro final invoice PDF: "Pay online" is a live hyperlink
  • QBO: balance invoice for test customer, amount = balance due, payment enabled
7 Pay Balance Invoice
manual + auto Path B or native connector
Do Click the Pay online link from the final invoice PDF and pay the remaining balance. Or: record payment directly in QBO against the balance invoice.
Auto: QBO payment webhook → Worker Path B (or native Receipts connector from P-7) marks the Scoro final invoice paid in full. Idempotency keys prevent duplicate receipts.
  • QBO: balance invoice status Paid, $0.00 balance
  • Scoro: final invoice status Paid in full; paid_sum = order total
8 Reconciliation Checks
manual

Scoro:

  • Prepayment: paid/reconciled; receipt = deposit amount
  • Final invoice: paid in full; paid_sum = order total; balance $0
  • No outstanding AR on test customer
  • Both PDFs show "Pay online" as a live hyperlink

QBO (Mhondoro Capital Partners, LLC):

  • Deposit invoice: Paid; payment recorded
  • Balance invoice: Paid; payment recorded
  • Customer Deposits liability: balance reflects deposit in + out
  • Total from test customer = order total (deposit + balance)
Deposit (D) = T × 50%[calc]
Balance (B) = T − D[calc]
D + B= T ✓

Troubleshooting Quick Reference

Symptom Most likely cause Action
Pay-link blank (Phase 4) Path A not fired or errored Wait 60s; refresh record. Check Worker log viewer
Pay-link = literal HTML "HTML format" flag OFF on custom field Scoro → Custom fields → c_qbo_invoice_link → enable flag → re-run Worker
Prepayment not paid (Phase 5) QBO webhook not wired / token mismatch / no KV entry Confirm P-4; check Worker logs; if KV missing, re-drive Path A first
"customer mapping unresolved" Scoro company → QBO customer not seeded Seed KV: qbomap:scoro_company:{id} → {customerId, billEmail}
No webhook in Worker logs Scoro trigger not wired / wrong URL Scoro → Triggers and actions → verify trigger + Worker URL
Final invoice not paid (Phase 7) KV entry for balance invoice missing (Path C incomplete) Check Path C completed; confirm qbomap:qbo_invoice:{balanceId} in KV
Duplicate receipts in Scoro Both native connector + Worker Path B fired Not harmful. If double-credit: void the duplicate receipt manually in Scoro UI
Key caveats Wait ~60s after creating the prepayment before sending the PDF — the pay-link populates after the Worker runs. Confirm it renders as a clickable link, not raw HTML. Keep test amounts small — real money flows.
Related: Bridge Worker · E2E quote-to-cash reference · E-mail kit · QuickBooks Online · Intuit Developer
ProMount by Vancomm — QBO Launch Validation · 2026-05-26 vancomm-qbo-launch.pages.dev