Integrations cookbook: accounting

Most tenants keep their book of record in Zoho Books, QuickBooks, or Xero. The platform pushes invoices, bills, payments, and journals; fetches payment confirmations back.

Before you start

• Decide which system is book-of-record. Usually the accounting tool (Zoho / QB / Xero). The platform becomes the operational source.
• Sync the CoA: platform accounts map to accounting tool accounts. See chart of accounts.
• Map tax codes: platform tax codes map to accounting tool tax rates.
• Map customers / vendors: match on tax ID or name. Unmatched entities create new on first sync.

Zoho Books

• OAuth from /app/admin/integrations → Zoho.
• Scopes: invoices, bills, contacts, items, chart of accounts, taxes, payments.
• Organisation id picker if you have multi-org.
• Sync cadence: real-time for new invoices / bills; 5-min for status changes; nightly reconciliation.

Known pitfalls

• Zoho rate limits: the platform throttles to their documented limit. Heavy backfills run overnight.
• Item-level vs line-level tax: keep line-level in sync with Zoho setting.
• Round-off differences: Zoho and the platform round slightly differently on multi-line invoices — the platform posts a round-off line automatically if the diff is ≤ 0.05.

QuickBooks Online

• OAuth from Intuit.
• Scopes: accounting.
• Company id picker for multi-company.
• Sync cadence: real-time via Intuit webhooks + nightly reconciliation.

Known pitfalls

• US edition differs from global: tax handling and 1099 tracking are US-specific.
• "Class" dimension: if you use classes, map the platform's cost centres to QB classes.
• Multi-currency requires QBO Plus or above.

Xero

• OAuth from Xero.
• Scopes: accounting transactions, contacts, accounting settings.
• Organisation picker for multi-org partnerships.
• Sync cadence: real-time via Xero webhooks + nightly reconciliation.

Known pitfalls

• Xero's bank-rec flow is opinionated: always reconcile inside Xero, not the platform.
• Tracking categories: similar to QB classes; map cost centres here.
• BAS / GST return runs in Xero; the platform provides input but doesn't file.

Common patterns

Avoid double-posting

Each platform document posts to accounting with a unique external reference. Attempts to resync an already-posted document are no-ops. Audit each resync event.

Handle failures

Sync failures appear in /app/admin/integrations/health. Common causes: expired OAuth (reauth), rate limit (will retry), validation error (data mismatch — fix source).

Backfills

On new setup, use the backfill wizard: select date range, dry-run first, then commit. Backfills respect rate limits and usually run 4–24 hours for a year of data.

Divergence handling

If someone edits in the accounting tool directly, the next sync pulls the change back. Conflict policy: last-writer-wins for most fields; payments are additive (never overwritten).