Invoice→QB sync suppressed on Cancelled work orders even when the invoice carries earned revenue (Cancellation service type)
Objective
- Allow Attik→QuickBooks invoice sync for cancelled work orders when the invoice still carries earned billable revenue (e.g. a Cancellation service-type fee line)
- Stop conflating work order status
Cancelledwith billable Cancellation service lines — they are independent concepts - Prevent payments from syncing to QuickBooks without a matching invoice, which leaves unapplied customer credits and breaks revenue recognition for brands that charge cancellation fees
Background
- Today, invoice sync is gated on work order status === confirmed only. When a job is cancelled, invoice sync is blocked and a QuickBooks invoice delete is queued — regardless of whether the invoice has charge lines or a non-zero total
- Payment sync remains enabled for cancelled Attik jobs, so QuickBooks can receive a payment with no invoice to apply against (unapplied credit / phantom liability on the customer account)
- Several brands use a billable service type named "Cancellation" (or similar) with an associated fee. That is not the same as setting the work order status to
Cancelled - Reference case — FHI624: Work order status
Cancelled(cancelled banner shown; top chip may still showPublishedbecause published report status takes precedence in the workorder header). InvoiceFHI624has a single Cancellation-type line "Same Day Cancelation - HI NOT Done" at $125.00, fully paid ($340.52 captured, $211.14 refunded, $0 balance). Invoice and payment did not sync to QuickBooks solely because the WO is cancelled — not because the invoice is empty or unsettled - Confirmed in code (investigation complete):
- Invoice queue/worker skip when
inspection.status !== 'confirmed':queueQuickbooksSync.ts(queueQuickbooksInvoiceSync,queueQuickbooksInvoiceSyncFromInspection) andupsertQuickbooksInvoice.ts(processQuickbooksInvoiceJob) - On status change to cancelled:
inspectionStream.tscallsqueueQuickbooksInvoiceDeleteusinginvoiceNumber - Payment queue allows confirmed or cancelled:
queueQuickbooksSync.ts(queueQuickbooksPaymentSync) - Refund path can queue invoice re-sync via
resolveQbPaymentSyncAction→sync_payment_and_invoice, but invoice workers still skip non-confirmed inspections - Workorder QuickBooks UI disables invoice manual sync when cancelled:
Quickbooks.tsx(canSyncInvoicerequiresstatus === 'confirmed'; subtext: "Cancelled—invoice sync off; payments can sync") - Charge line → QB mapping uses service QB item ref on each charge:
qbChargeLineItems.ts/buildQbInvoiceLineItems.ts(no special-case skip for Cancellation service type today)
Product Decisions
Locked
- Problem framing — The bug is status-based suppression of invoice sync on cancelled jobs, not missing Cancellation service configuration in general
- Naming collision — Billable Cancellation service type (fee line on invoice) must not be treated the same as work order status
Cancelled - Reference validation — FHI624 is the acceptance example: cancelled WO, paid $125 Cancellation fee, zero balance, should sync invoice + apply payment in QuickBooks
- Attik-created jobs only — QuickBooks invoice sync applies to
jobCreationType === 'attik'(existing integration scope)
Open
- Net billable threshold — What condition should allow invoice sync on a cancelled WO:
total > 0,balance >= 0with at least one charge line, only when a Cancellation-type service is present, or any non-zero invoice regardless of line types? - Cancel-time invoice delete — When a WO is cancelled but retains billable revenue, should
queueQuickbooksInvoiceDeletestill run (removing a previously synced invoice), or should delete be suppressed / replaced with upsert when net billable revenue exists? - Partial refund pattern (FHI624) — After partial refund on a cancelled job, should the QuickBooks invoice total reflect the retained amount ($125), the original charge total, or follow existing refund-adjustment logic (
sync_payment_and_invoice) once the status gate is fixed? - Manual sync UX — Should the workorder Integrations → QuickBooks "Sync to QuickBooks" action be enabled for cancelled jobs that meet the net-billable criteria, or queue-only via automatic paths?
- Empty cancelled invoices — Confirm continued suppression when invoice total is zero / no chargeable lines (no change to current intent for truly empty cancelled jobs)
Scope
Backend (attik-backend)
src/util/functions/quickbooks/queueQuickbooksSync.ts— invoice sync enqueue requiresstatus === 'confirmed'today; payment sync allowsconfirmed | cancelledsrc/events/subscribers/quickbooksIntegration/upsertQuickbooksInvoice.ts—processQuickbooksInvoiceJobhard-skips non-confirmed inspections before QB API callssrc/events/streamHandlers/inspectionStream.ts— on cancel:queueQuickbooksInvoiceDelete; on confirm/charge/reschedule:queueQuickbooksInvoiceSyncFromInspectionsrc/events/streamHandlers/chargeStream.ts— charge insert/update triggers invoice sync (still subject to confirmed gate in queue helper)src/events/streamHandlers/paymentStream.ts— payment insert/update triggers payment sync; refund policy inqbPaymentSyncPolicy.tsmay queue invoice sync that is then blockedsrc/util/functions/quickbooks/buildQbInvoiceLineItems.ts/qbChargeLineItems.ts— charge lines map via_serviceId.quickbooks.id; verify Cancellation services have correct QB item mapping per brand (data/config, not code branch today)src/routes/quickbooks.ts— manualPOST /sync-invoice/:inspectionIdendpoint (no status check at route level; worker skip applies)
Frontend (attik-frontend)
src/app/tools/inspections/[id]/components/integrations/Quickbooks.tsx—canSyncInvoiceand cancelled subtext;expectedQbInvoiceTotalfor balance comparisonsrc/app/tools/inspections/[id]/components/InspectionWorkorderShell.tsx— cancelled banner vsPropertyStatusChipshowingpublishedwheninspection.published(orthogonal to QB sync; explains FHI624 header confusion but out of scope unless separately fixed)
Out of scope (unless expanded)
- Changing published vs cancelled header chip priority (separate UX concern)
- QuickBooks sync for Spectora-created jobs
- HubSpot / other integrations that also branch on
status === 'cancelled'
References
- Reference case: invoice
FHI624— cancelled WO, Cancellation fee line, paid zero balance - QuickBooks integration entry points:
queueQuickbooksSync.ts,upsertQuickbooksInvoice.ts,Quickbooks.tsx - Related cancellation-fee naming in ISN import:
isn/historicalImportPayments.ts(isIsnSameDayCancellationCatalogFeeName)
Status: Planned
Log in to comment and vote
No comments yet
Be the first to share your thoughts.