Overview

Clava integrates with two accounting platforms: QuickBooks Online (QBO) and Xero. Both integrations aggregate sales by revenue category for the selected sync period, then sync that summary to QuickBooks Online or Xero as a journal entry in your chart of accounts.

The integration does not synchronise individual sales transactions.

The platforms differ in how journal entries are structured, how location tracking works, how account types are handled, and how tax is handled.

This guide covers setup, configuration, and sync behavior for both platforms.

Supported Platforms at a Glance

Feature	QuickBooks Online	Xero
Journal entry type	Journal Entry (`JournalEntry`)	Manual Journal (`ManualJournal`)
Voiding / deleting	Permanently deleted	Voided (Xero does not support true deletion)
Location tracking mechanism	Departments (requires QBO Plus or Advanced)	Tracking Categories + Tracking Options
Location tracking requirement	`Track Departments` must be enabled in QBO Preferences	A Tracking Category must be configured on the connection
Account types	`AccountType` and `AccountSubType` (both supported)	`AccountType` only (sub-types not supported)
Tax rate mapping	Required for auto-sync; warnings shown in manual sync	Optional
Tax line posting	Explicit credit lines to liability accounts	Explicit credit lines to liability accounts (when mapped)

Getting Started

Connecting QuickBooks Online

In Settings → Integrations → Accounting, enable the QuickBooks toggle.
Click Connect QuickBooks. You will be redirected to Intuit's OAuth authorization page.
Sign in and authorize the connection.
After being redirected back, a Connection Configuration modal will open. Give the connection a name, select which locations it covers, and choose a mapping mode (see Mapping Modes below).
Click Save.

Connecting Xero

In Settings → Integrations → Accounting, enable the Xero toggle.
Click Connect Xero. You will be redirected to Xero's OAuth authorization page.
Sign in, select your Xero organization, and authorize the connection.
After being redirected back, the Connection Configuration modal will open. In addition to the name, locations, and mapping mode, you will see a Tracking Category selector — see Location Tracking: Xero for details.
Click Save.

Multiple connections: You can create more than one connection per provider (for example, separate QBO organizations for different brands). Each connection is configured and synced independently.

Connection Configuration

After initial setup, you can reopen the configuration modal at any time using the Edit (pencil) icon on a connection card.

Locations

Select which of your business locations this connection covers. A location can only belong to one connection per provider at a time.

Mapping Mode {#mapping-modes}

Each connection operates in one of two modes:

Mode	Description
Single book	One shared set of revenue category → account mappings applies to all locations on this connection. One journal entry is produced per sync.
Per-location book	Each location has its own independent set of mappings. One journal entry is produced per location per sync.

These modes are mutually exclusive. Switching from one to the other does not automatically migrate existing mappings.

Default for new and existing connections: Single book.

Choosing a mode: Use Single book if all locations share the same chart of accounts. Use Per-location book if each location maintains separate books.

Revenue Category Mappings

Revenue categories are Clava's (Fittr) classification for different types of sales (Pack, Pass, Subscription, Drop-in, Giftcard, Refunds, etc.). Each category must be mapped to a specific account in your chart of accounts before a sync can run.

Opening the Mapping Modal

Click Map Accounts on a connection card to open the mapping modal. The modal loads your chart of accounts directly from QuickBooks or Xero.

Single Book Mode

All categories are shown in a single list. Select an account for each category. The Deposit Account (the asset account that receives the offsetting debit) is also set here and is shared across all locations.

Save when done.

Per-Location Book Mode

A location selector appears at the top of the modal. Choose a location to view and edit that location's mappings. You can switch between locations — unsaved changes for each location are held as drafts until you save.

The Deposit Account is shared across all locations on the connection (set once, applies to all).

When you save, all locations with unsaved changes are saved in a single operation.

Sync precondition: In Per-location book mode, every location on the connection must have at least one mapping before a preview or sync can run. The sync will not proceed if any location has no mappings at all.

Account Types and Sub-Account Types

When mapping revenue categories, tax rates, or deposit accounts, the dropdown selectors display accounts from your chart of accounts as loaded directly from your accounting platform.

Each account is shown with its account type and (for QuickBooks Online) sub-account type to help you identify the correct account.

Clava applies filtering to ensure only accounts suitable for journal entry posting are available in each context. Different dropdowns use different filtered views of your chart of accounts.

QuickBooks Online

QuickBooks Online accounts include both an Account Type and an Account Sub-Type, both of which are displayed in mapping dropdowns.

Account types available for revenue category and deposit account mapping (11 types — subledger-linked types are excluded):

Account Type	Typical Use
`Bank`	Cash accounts, checking, savings
`Other Current Asset`	Short-term assets not in other categories
`Fixed Asset`	Long-term tangible assets
`Other Asset`	Long-term assets not in other categories
`Credit Card`	Credit card accounts
`Equity`	Owner's equity, retained earnings
`Income`	Revenue from primary business activities
`Other Income`	Revenue from non-primary activities
`Expense`	Operating expenses
`Other Expense`	Non-operating expenses
`Cost of Goods Sold`	Direct costs of producing goods sold

Excluded types: Accounts Receivable and Accounts Payable are excluded because they require a customer or vendor reference (EntityRef) on every journal line, which is not available in Fittr's aggregated sales revenue sync. Long Term Liability and Other Current Liability are excluded from general mapping because they are reserved for tax liability mapping (see below).

Excluded sub-types: The following specific sub-types are also filtered out from the general account list:

UndepositedFunds
OpeningBalanceEquity
PayrollLiabilities
TaxPayable

Sub-Account Types are supported and displayed alongside the account type in dropdowns. These are determined by QuickBooks Online and vary by account type (for example, Cash on hand or Savings under Bank, or Office Equipment under Fixed Asset).

Account types available for tax rate mapping (3 types, via a separate endpoint):

Account Type	Typical Use
`Other Current Liability`	Short-term tax liabilities
`Long Term Liability`	Long-term tax liabilities
`Expense` (subtype `TaxesPaid` only)	Tax expense accounts

Xero

Xero accounts include an Account Type only. Xero does not support sub-account types — this field will always appear as blank in mapping dropdowns.

Account types available for revenue category and deposit account mapping (all active types except BANK):

Account Type	Typical Use
`CURRENT`	Current assets
`CURRLIAB`	Current liabilities
`DEPRECIATN`	Depreciation
`DIRECTCOSTS`	Direct costs
`EQUITY`	Equity accounts
`EXPENSE`	Operating expenses
`FIXED`	Fixed assets
`INVENTORY`	Inventory
`LIABILITY`	General liabilities
`NONCURRENT`	Non-current assets
`OTHERINCOME`	Other income
`OVERHEADS`	Overhead expenses
`PREPAYMENT`	Prepayments
`REVENUE`	Revenue
`SALES`	Sales
`TERMLIAB`	Term liabilities
`PAYGLIABILITY`	PAYG liabilities
`SUPERANNUATIONEXPENSE`	Superannuation expense
`SUPERANNUATIONLIABILITY`	Superannuation liability
`WAGESEXPENSE`	Wages expense
`WAGESPAYABLELIABILITY`	Wages payable liability

Note: BANK type accounts are excluded from the chart of accounts query and will not appear in revenue category or deposit account dropdowns for Xero connections.

Account types available for tax rate mapping (1 type, via a separate endpoint):

Account Type	Typical Use
`LIABILITY`	Tax liability accounts

Account Display in Mapping Dropdowns

In all mapping modals (revenue categories, tax rates, and deposit account), each account is displayed in the format:

[Code] / [AccountType] / [AccountSubType]

QuickBooks Online: Both AccountType and AccountSubType are populated (e.g., 4001 / Income / Discounts/Refunds).
Xero: Only Code and AccountType are populated; AccountSubType is blank (e.g., 200 / REVENUE).

Recommended Account Type Mappings

For correct financial reporting, we recommend the following mappings:

Mapping	Recommended Account Type
Revenue category → income account	`Income` / `Other Income` (QBO) or `REVENUE` / `SALES` / `OTHERINCOME` (Xero)
Tax rate → liability account	`Other Current Liability` / `Long Term Liability` (QBO) or `LIABILITY` (Xero)
Deposit / bank account	`Bank` (QBO) or `CURRENT` (Xero — `BANK` is excluded; use a current asset account)

Tax Rate Mappings

QuickBooks and Xero: Tax rate mapping is required for scheduled auto-syncs and strongly recommended for manual syncs.

How Tax Lines Work

When tax rates are mapped, the journal entry uses net (pre-tax) revenue for each income account credit line and adds explicit credit lines for each mapped tax rate, posting to the configured liability account. The total debit (deposit account) always equals the original gross amount regardless of how many rates are mapped.

Example journal entry (with tax mapping):

CR  Sales — Pass             $100.00   (net revenue) 
CR  Sales — Pack              $50.00   (net revenue) 
CR  Tax Payable 10%           $15.00   (explicit tax liability line) 
DR  Undeposited Funds        $165.00   (original gross — unchanged)

When a tax rate has no mapping, the tax amount remains embedded in the gross revenue line for that category. A warning is shown in the preview and sync confirmation. No lines are lost; the journal entry always balances.

Configuring Tax Rate Mappings

Click the Tax Rates button on a connection card to open the tax mapping modal.

Each platform tax rate is listed with its rate percentage. Select a liability account from your chart of accounts for each rate.

Single book: One set of mappings for all locations.
Per-location book: Mappings are loaded for each location. All locations' mappings are loaded up front when the modal opens. Switch between locations using the selector.

QuickBooks: Auto-Sync Tax Validation

The scheduled auto-sync checks whether all tax rates are mapped before running. If any rate is unmapped, the auto-sync job skips the connection entirely for that run. Manual syncs are not blocked — they will proceed with an unmapped-tax warning.

Location Tracking

Location tracking allows a Single book connection to post revenue broken down by location within a single journal entry. Each location's revenue and tax lines carry a tracking tag so your accounting platform can report by location.

Per-location book mode does not use location tracking. It produces separate journal entries per location instead.

QuickBooks: Departments

Location tracking in QuickBooks uses Departments.

Requirements:

QuickBooks Online Plus or Advanced plan.
"Track departments" must be enabled in QBO → Settings → Account and Settings → Advanced → Categories.

Mapping locations to Departments:

Click the Locations button on a connection card to open the location mapping modal.

For each location, choose one of two options:

Option	Description
Create new department	Fittr creates a new Department in QuickBooks for this location when the mapping is saved.
Map to existing	Select an existing QuickBooks Department to link to this location.

After saving, Fittr immediately syncs the mappings with QuickBooks. Each row shows a sync status (pending, synced, or error). Location tracking cannot be used until all location mappings show synced.

Xero: Tracking Categories {#xero-tracking-categories}

Location tracking in Xero uses Tracking Categories and Tracking Options.

Requirements:

A Tracking Category must exist in Xero and be set on the connection (not archived).

Setting up the Tracking Category:

In the Edit connection modal, select the Xero Tracking Category you want to use for location breakdown. This dropdown loads tracking categories from your Xero organization. Archived categories are excluded.

Mapping locations to Tracking Options:

Click the Locations button on a connection card. The modal lists your locations alongside available Tracking Options within the selected category.

Option	Description
Create new tracking option	Fittr creates a new Tracking Option in Xero for this location.
Map to existing	Select an existing Tracking Option to link to this location.

As with QuickBooks, all rows must reach synced status before location tracking is active.

Xero note: Xero does not allow deleting Tracking Options once they exist. If you select "Create new", the option will persist in Xero even if you later remove the location mapping.

Syncing

Manual Sync

Click Sync on a connection card.
Select the date range for the sync (day, week, or month).
If the connection uses QuickBooks, a tax validation status is shown. A warning appears if any tax rates are unmapped.
Click Preview to generate a journal entry preview without posting anything.

Journal Entry Preview

The preview shows the complete set of lines that will be posted:

Credit lines — one per mapped revenue category (net amount if tax lines are present; gross if not).
Tax credit lines — one per mapped tax rate, to the configured liability account.
Debit line(s) — one per location (or one total for single-location syncs), to the deposit account. Always equals the sum of all credit lines.

If tax rates are unmapped, a warning banner shows the total unmapped tax amount and the affected rates. The preview can still be confirmed.

If a journal entry already exists for the same connection and date range, a duplicate warning is shown. You can still proceed; a new entry will be posted alongside the existing one.

Click Confirm Sync to post the journal entry to QuickBooks or Xero.

Per-Location Book Sync

In Per-location book mode, the sync creates one journal entry per location. Each location's journal entry:

Includes only that location's revenue data.
Uses that location's configured revenue category mappings.
Uses that location's configured tax rate mappings.
Does not mix data from other locations.

If a location has no revenue in the selected date range, it is skipped silently (no empty journal entry is created).

If a location's mappings are incomplete, sync is blocked for that location and an error is returned identifying the missing mappings. Other locations are still processed.

Auto-Sync

Auto-sync runs automatically on a schedule you configure per connection. Supported frequencies:

Frequency	When it runs	Date range posted
Daily	Each day	Previous day
Weekly	Every Monday	Prior Monday–Sunday
Monthly	1st of each month	Prior calendar month

Auto-sync is gated on:

Connection status is connected.
Deposit account is configured.
Required mappings are present for all active locations.
QuickBooks only: All tax rates are mapped. If any are unmapped, the auto-sync job skips the connection for that run.
An optional auto-sync start date can be set on the connection; syncs are skipped until that date is reached.

Sync Logs

Each connection card shows a history of sync attempts in an accordion list. Each log entry shows:

Date range synced
Status (success or failed)
Number of lines posted
Tax line details (rates, amounts, liability accounts)
Warnings for unmapped tax rates

From a sync log entry you can delete the journal entry from QuickBooks or Xero directly.

QuickBooks: The journal entry is permanently deleted from QBO.
Xero: The manual journal is voided (set to VOIDED status). Xero does not support true deletion of posted manual journals.

Troubleshooting

"All locations must have at least one mapping" error

You are in Per-location book mode and one or more locations on the connection have no revenue category mappings. Open Map Accounts, switch to each location, and assign at least one account mapping.

Tax validation warning in sync modal (QuickBooks)

One or more platform tax rates do not have a liability account mapped. Open Tax Rates and assign a liability account to every listed rate. Until this is done, scheduled auto-sync will not run for this connection.

Location mapping shows "error" status

Fittr could not create or verify the Department (QuickBooks) or Tracking Option (Xero) in the provider. Check that:

Your OAuth token is still valid (try disconnecting and reconnecting).
For QuickBooks: your plan supports Departments (Plus or Advanced required).
For Xero: the Tracking Category is not archived.

Retry saving the location mapping after resolving the issue. Sync is blocked until all location mappings reach synced.

Duplicate journal entry warning

A journal entry was already posted for this connection and date range. If the previous entry was incorrect, delete it from the sync logs first, then run the sync again.

Xero: "Cannot delete journal entry"

Xero does not support deletion of posted manual journals. The integration will void the entry instead. Voided entries remain visible in Xero but are excluded from reporting. This is a Xero platform limitation.

Advanced Accounting Integration setup guide