Accounting Integrations

Connect Beeswax to external accounting software.

Overview

Accounting Integrations allow you to connect Beeswax to external accounting software so your invoices, expenses, contacts, and chart of accounts stay synchronised across both platforms.

Key features:

  • Xero integration — Connect your Xero organisation to automatically sync finalised invoices and expenses.
  • OAuth2 authentication — Secure connection using industry-standard OAuth2 (no passwords stored).
  • Automatic sync — Finalised invoices and expenses are periodically pushed to your connected accounting platform.
  • Payment webhooks — Payments recorded in Xero are automatically reflected in Beeswax.
  • Account mapping — Map your Beeswax transaction accounts to their Xero equivalents for accurate categorisation.
  • Contact sync — Company/contact information is sent to Xero when invoices or expenses are synced.

Note: Accounting integrations require the accounting add-on on your subscription plan. Trial accounts have access by default.

Connecting to Xero

To connect your Xero account:

  1. Navigate to Settings → Accounting Integrations.
  2. Click Connect to Xero.
  3. A Xero login window will open — sign in and authorise Beeswax to access your organisation.
  4. Once authorised, the window closes and your connection status updates automatically.

What Happens on Connection

  • Beeswax stores an OAuth2 access token and refresh token (valid for 60 days).
  • Tokens are automatically refreshed before they expire.
  • The name of the connected Xero organisation is displayed on the integration settings page.

Requirements

  • You must have an active Xero account and organisation.
  • Only Owners and Super Admins can connect or disconnect integrations.
  • The accounting add-on must be active on your subscription.

How Syncing Works

Once connected, Beeswax periodically syncs your financial data to Xero.

What Gets Synced

  • Invoices — Finalised invoices are pushed to Xero as Accounts Receivable (ACCREC) invoices.
  • Expenses — Finalised expenses are pushed to Xero as Accounts Payable (ACCPAY) bills.
  • Contacts — Company details are created or updated in Xero when their invoices or expenses sync.
  • Transaction accounts — Beeswax accounts are mapped to Xero accounts for correct categorisation.

Sync Behaviour

  • Only entries modified since the last successful sync are processed (incremental sync).
  • Draft entries are never synced — only finalised, sent, or approved entries.
  • Entries are processed in batches to ensure reliability.
  • The sync timestamp updates after each successful batch.
  • Original modification timestamps are preserved to prevent sync loops.

Duplicate Prevention

The system uses two methods to prevent duplicate entries in Xero:

  1. Resource ID check — Looks for an existing mapping between the Beeswax entry and a Xero invoice.
  2. URL-based check — Searches Xero for invoices that reference the Beeswax entry ID.

If a valid, non-voided invoice is found in Xero, the entry is skipped.

Payment Webhooks

When a payment is recorded against an invoice or expense in Xero, Beeswax automatically receives a webhook notification and creates a corresponding payment record.

How It Works

  1. Xero sends a webhook event to Beeswax when an invoice is updated or a payment is created.
  2. Beeswax validates the webhook signature using HMAC-SHA256.
  3. The system finds the corresponding Beeswax entry via the Xero invoice mapping.
  4. A payment is created in Beeswax with the correct amount, date, and bank account.

Payment Matching

  • The system attempts to map the Xero bank account to a Beeswax bank account.
  • If no mapping exists, the default bank account is used.
  • Duplicate payments are prevented by checking (amount, date) pairs.
  • If the Xero payment amount exceeds the remaining balance in Beeswax, a notification is sent.

Account Mapping

For accurate financial categorisation, you should map your Beeswax transaction accounts to their Xero equivalents.

How to Map Accounts

  1. Navigate to the Chart of Accounts page.
  2. Click the Xero mapping icon next to any account.
  3. Select the corresponding Xero account from the dropdown.
  4. The mapping is saved immediately.

Mapping Rules

  • Asset accounts map to Xero BANK, CURRENT, EQUITY, FIXED, INVENTORY, NONCURRENT, and PREPAYMENT types.
  • Expense accounts map to Xero DEPRECIATN, DIRECTCOSTS, EXPENSE, and OVERHEADS types.
  • Income accounts map to Xero OTHERINCOME, REVENUE, and SALES types.
  • Loan (liability) accounts map to Xero CURRLIAB, LIABILITY, and TERMLIAB types.

Unmapped Accounts

If an invoice or expense uses a Beeswax account that has no Xero mapping, the system falls back to a default account and sends an email notification so you can correct the mapping.

Sync History

You can view the history of synced entries from Settings → Accounting Integrations.

The sync history table shows:

  • Document number — The Beeswax invoice or expense number.
  • Type — Invoice or Expense.
  • Title — The document title.
  • Sync status — Whether the entry was successfully synced.
  • Xero ID — The corresponding Xero invoice ID.
  • Date created — When the sync occurred.
  • Total amount — The document total.

The list supports infinite scroll for large sync histories.

Error Handling & Notifications

The integration sends email notifications for scenarios that require your attention:

  • Missing account mapping — A transaction account was not mapped to Xero; the default account was used instead.
  • Payment mismatch — A payment received from Xero exceeds the remaining balance on the Beeswax entry.
  • Manual intervention required — A paid or locked invoice in Xero cannot be updated automatically.
  • API errors — Authentication failures or Xero API errors requiring reconnection.
  • Voided invoice replacement — An expense with a voided Xero invoice was automatically replaced with a new one.

Manual Intervention

Some scenarios require manual action:

  • Paid invoices — Cannot be updated in Xero once marked as paid. These are flagged for manual review.
  • Voided sales invoices (ACCREC) — Due to Xero's unique invoice number requirement, voided sales invoices cannot be automatically replaced.
  • Voided expense bills (ACCPAY) — These are automatically replaced with a new Xero invoice.

Disconnecting

To disconnect your Xero integration:

  1. Navigate to Settings → Accounting Integrations.
  2. Click Disconnect.
  3. The OAuth2 tokens are cleared and syncing stops immediately.

Existing sync history and account mappings are preserved for reference. Reconnecting later will resume syncing from where it left off.

Permissions by Role

Action Owner Super Admin Admin Accountant General Client
Connect to Xero Yes Yes No No No No
Disconnect from Xero Yes Yes No No No No
View sync history Yes Yes Yes Yes No No
Map transaction accounts Yes Yes No Yes No No

Key Notes

  • Only Owners and Super Admins can connect or disconnect accounting integrations.
  • Accountants can view sync history and map transaction accounts but cannot manage the connection itself.
  • Admins can view sync history but cannot connect, disconnect, or map accounts.
  • General Users, Contractors, and Clients cannot access accounting integration features.
  • Accounting integrations require the accounting add-on on your subscription plan.