Docs

Integration Sync and Troubleshooting

Monitor sync activity, review logs, and resolve common integration issues.

Integration Sync and Troubleshooting

You can monitor data sync activity, review detailed logs, and troubleshoot integration issues from the Integrations section. This page covers the sync lifecycle, the Integration Logs page, and common problems with solutions.

Required role: Owner or Admin

How Syncing Works

When you connect and link a company from your accounting provider, an initial full sync pulls all available financial data. After that, periodic syncs keep your data current by pulling only new or changed records.

The sync process runs as a background job. You can continue working while syncs are in progress. When a sync completes, the Data Feed page reflects the updated "Last Synced" timestamp.

Sync Statuses

Each company in the Data Feed table shows a sync status:

  • Synced -- Data is up to date with the latest sync.
  • Needs Resync -- The company is due for a data refresh, or a previous sync encountered an issue.
  • Syncing -- A sync job is currently in progress.

Integration Logs Page

The Integration Logs page (Integrations > Logs) has a searchable record of all sync activity for your organization. The page has two views: a company summary and a company detail view.

Company Summary View

When you open Integrations > Logs from the sidebar, you see a grid of cards -- one for each connected company. Each card shows:
  • Company name and provider logo (QuickBooks or Xero)
  • Total logs -- The number of log entries for that company
  • Errors -- How many log entries are errors
  • Milestones -- How many log entries are milestones
  • Last activity -- A relative timestamp of the most recent log entry

Click a company card to view its detailed logs.

Company Detail View

After selecting a company, the logs table shows the following columns:

  • Date -- When the event occurred
  • Accounting Software -- QuickBooks or Xero
  • Company -- The company the event relates to
  • External Account -- The provider account (email or name) associated with the log entry
  • Log Type -- Either "Milestone" (key sync progress events) or "Event" (other sync activity)
  • Message -- A description of the sync event (e.g., "Data sync started", "Normalization complete")
  • Status -- Either "Success" (green indicator) or "Error" (red indicator)

To return to the company summary, click the All Companies link at the top of the page.

Filtering Logs

Use the filter controls in the detail view to narrow down logs by:

  • Accounting Software -- QuickBooks or Xero
  • Company -- Text search by company name
  • External Account -- Text search by account email or name
  • Log Type -- Milestone or Event
  • Message -- Text search within log messages
  • Status -- Success or Error
  • Date -- Filter by specific date

The logs table supports server-side pagination. You can adjust the page size (25, 50, or 100 entries per page).

Understanding Log Entries

Logs have two independent classifications:

  • Log Type indicates the category of event:

    • Milestone logs track key sync progress events (e.g., "Sync started", "Chart of accounts imported", "Transactions synced")
    • Event logs track other sync-related activity

  • Status indicates the outcome:

    • Success means the event completed without issues
    • Error means a problem occurred during the event

Error logs include a log body with additional details about what went wrong. This information can help you or Levelup support diagnose the issue.

Triggering a Manual Re-sync

You can manually trigger a re-sync at any time from the Data Feed page:

  1. Navigate to Integrations > Data Feed.
  2. To re-sync a single company, open the row action menu and select Resync.
  3. To re-sync multiple companies, select them using the checkboxes and click Auto Resync.
  4. To re-sync all companies that need it, click Auto Resync All.

A re-sync pulls fresh data from your accounting provider and updates all financial records.

Background Job Tracking

When a sync or re-sync is triggered, it runs as a background job. You can track active sync workers in several places:

  • A status indicator on the company dashboard shows when workers are actively syncing.
  • On the Chart of Accounts Mapping page, a banner appears when a company is being re-synced, warning that changing mappings may restart the sync process.
  • Recently completed workers are tracked so you can see which companies finished syncing.

Common Issues and Solutions

Expired OAuth Token

Symptom: Syncs stop working. The Data Feed shows an invalid token status for affected companies.

Solution:

  1. Go to Integrations.
  2. On the affected provider card, open Manage and select Reconnect.
  3. Complete the OAuth authorization flow.
  4. Syncing resumes automatically.

If the original user who connected is no longer available, another team member can connect their own account and use the Update Token User action on the Data Feed page.

Consent Denied or Authorization Error

Symptom: The OAuth callback page shows "Authorization Denied" or a similar error.

Solution:

  1. Click Back to Integrations on the error page.
  2. Try connecting again.
  3. When your accounting provider asks for permission, approve all requested access.

No Companies Appear After Connecting

Symptom: You complete the OAuth flow successfully, but no companies show up on the Data Feed page.

Solution:

  1. Verify that your accounting provider account has access to at least one company or organization.
  2. For Xero, confirm you selected the correct organizations when granting access.
  3. Check that your Levelup organization has available companies to link to.

Sync Errors in Logs

Symptom: The Integration Logs page shows error entries for a company.

Solution:

  1. Review the error details in the log entry for specific information.
  2. Try triggering a manual re-sync from the Data Feed page.
  3. If the error persists, check that the OAuth token is still valid.
  4. Contact Levelup support if the issue continues after re-syncing and re-authenticating.

Duplicate Connection Error

Symptom: When trying to connect, you see a message that the user already has an integration to that accounting software.

Solution:

  1. Go to Integrations > Data Feed to manage your existing linked companies.
  2. If you need to connect a different account, disconnect the current one first from the Integrations overview page.

Next Steps

Previous

Manage Integrations

Next

Chart of Accounts Mapping

Command Palette

Search for a command to run...