QuickBooks Online Integration

BlockManOS integrates with QuickBooks Online (QBO) to synchronise service charge data. Developments are pushed to QBO as customer records, and service charge demands are pushed as invoices. When invoices are paid in QuickBooks, the payment status syncs back to BlockManOS in real time via webhook.

Financials remain in QuickBooks — this integration provides visibility only, not full financial replication.

---

Prerequisites

Before setting up the integration you need:

1. A QuickBooks Online account (sandbox or production).
2. An app registered in the Intuit Developer portal with OAuth2 enabled.
3. The following environment variables configured in your BlockManOS deployment:

Variable	Description
QUICKBOOKS_CLIENT_ID	OAuth2 Client ID from Intuit Developer portal
QUICKBOOKS_CLIENT_SECRET	OAuth2 Client Secret from Intuit Developer portal
QUICKBOOKS_REDIRECT_URI	OAuth2 callback URL — must exactly match the redirect URI registered in Intuit Developer (e.g. https://app.blockman.ie/dashboard/integrations/quickbooks/callback)
QUICKBOOKS_ENVIRONMENT	sandbox or production (defaults to sandbox)
QUICKBOOKS_WEBHOOK_VERIFIER_TOKEN	HMAC verification token configured in the QBO developer portal webhook settings

The feature is disabled and hidden in the UI when these variables are not set.

---

Connecting to QuickBooks

1. Go to Dashboard → Integrations → QuickBooks.
2. Click Connect to QuickBooks.
3. You are redirected to the Intuit authorisation page. Sign in and grant access.
4. Intuit redirects back to BlockManOS (/dashboard/integrations/quickbooks/callback). The OAuth2 code is exchanged for access and refresh tokens, which are stored against your organisation.
5. The integration page shows a Connected status badge. Use the Test Connection button to verify the stored tokens are valid.

To disconnect, click Disconnect on the integration page. This revokes the stored tokens and removes the QBO connection for your organisation.

---

Syncing Developments as Customers

Each development (block) must be pushed to QuickBooks as a customer before its demands can be synced as invoices.

1. On the QuickBooks integration page, go to the Sync section.
2. Select the development from the dropdown.
3. Click Sync as Customer.
4. The development appears in the synced entity list with a QBO customer ID and a Synced status badge.

If the development has already been synced, re-syncing will update the existing QBO customer record.

---

Syncing Service Charge Demands as Invoices

Issued service charge demands can be pushed to QuickBooks as invoices.

1. The parent development must already be synced as a QBO customer (see above).
2. Select the demand from the dropdown in the Sync section.
3. Click Sync as Invoice.
4. The demand appears in the synced entity list with a QBO invoice ID and a status badge (Outstanding, Paid, Overdue, or Voided).

---

Invoice Status Synchronisation

Automatic (via Webhook)

When an invoice is paid, updated, voided, or deleted in QuickBooks, Intuit sends a webhook notification to:

POST /api/webhooks/quickbooks

BlockManOS verifies the intuit-signature HMAC header against QUICKBOOKS_WEBHOOK_VERIFIER_TOKEN, then looks up the matching invoice mapping and updates its status. The Webhook Event Log on the integration page shows every incoming event, its type, and whether it was processed successfully.

Supported event types:

Event	Action
invoice.paid	Updates QBO status to Paid
invoice.updated	Queries QBO for the latest invoice state and updates accordingly
invoice.deleted	Sets QBO status to Voided
invoice.voided	Sets QBO status to Voided

BlockManOS responds to all webhook requests within 10 seconds (as required by Intuit). Errors during processing are logged against the event record and do not cause webhook retries to fail permanently.

Manual Refresh

Staff can manually pull the latest status of any individual invoice:

1. Find the invoice in the synced entity list.
2. Click the Refresh button next to it.
3. BlockManOS queries QBO directly and updates the status badge in real time.

---

Dashboard Reference

The Integrations → QuickBooks page includes:

Section	Description
Connection Status	Shows whether the organisation is connected to QBO, with a Test and Disconnect button
Sync Summary	Cards showing total customers synced, and invoice counts broken down by status (Paid, Outstanding, Overdue, Voided)
Sync Actions	Dropdowns and buttons to push a development as a customer or a demand as an invoice
Synced Entities	Full list of all synced developments and demands, with QBO IDs, status badges, last synced time, and per-invoice refresh buttons
Webhook Event Log	Chronological log of all webhook events received from QBO, including event type, QBO entity ID, and processing status

---

Database Tables

Table	Purpose
qb_configs	Stores OAuth2 access/refresh tokens and QBO company (realm) info per organisation
qb_entity_mappings	Maps BlockManOS developments and demands to QBO customers and invoices
qb_webhook_events	Immutable audit log of all incoming QBO webhook events

---

Troubleshooting

Connection fails after OAuth redirect

• Confirm QUICKBOOKS_REDIRECT_URI exactly matches the redirect URI registered in the Intuit Developer portal (including scheme, domain, and path).
• Confirm QUICKBOOKS_CLIENT_ID and QUICKBOOKS_CLIENT_SECRET are correct.

Webhooks not updating invoice status

• Confirm QUICKBOOKS_WEBHOOK_VERIFIER_TOKEN matches the token configured in QBO's webhook settings.
• Check the Webhook Event Log on the integration page for processError messages.
• Ensure the webhook endpoint (/api/webhooks/quickbooks) is publicly reachable by Intuit's servers.

Invoice sync fails with "customer not synced" error

• The parent development must be synced as a QBO customer before any of its demands can be pushed as invoices.

Sandbox vs production

• Set QUICKBOOKS_ENVIRONMENT=sandbox for testing. Switch to production only when using a live QBO company. Sandbox and production use different Intuit OAuth2 endpoints.