Agiled Docs

QuickBooks and Xero are finance integrations with OAuth, sync support, run history, and webhook support.

Use these integrations when Agiled finance data needs to stay aligned with your accounting system. Decide which system is the source of truth before turning on sync so customers, items, invoices, and payments do not drift.

Before Connecting

Confirm the accounting company or tenant, accounting permissions, tax setup, currency, and item structure. Clean up duplicate customers or products before the first sync when possible.

If you are migrating from spreadsheets or another tool, run a small test sync before connecting a large live dataset.

Decide whether Agiled or the accounting system owns invoice numbers, tax settings, payment status, customer names, and item catalog changes. Write this down before the first live sync so users know where to make corrections.

Connect QuickBooks or Xero

Open Settings > Apps.
Choose QuickBooks or Xero.
Start the OAuth connection.
Approve access to the correct company or tenant.
Return to Agiled and confirm the connection is active.
Run sync from the app detail panel if needed.

After OAuth returns to Agiled, verify the connected company name or tenant. This is the most important check when a user has access to multiple accounting companies.

What Syncs

QuickBooks sync can cover:

Customers
Items
Invoices
Payments

Xero sync can cover:

Contacts
Items
Invoices
Payments

First Sync Workflow

Connect the provider.
Review sync settings and supported resources.
Run one limited sync if the app panel supports it.
Review imported or matched customers and items.
Check invoices and payments for tax, currency, and status accuracy.
Review the run history before enabling repeated operational use.

Use a narrow date range or small sample when available. A first sync should prove matching and tax behavior before it imports or updates a large accounting history.

Reconciliation Checks

Compare a sample customer, item, invoice, and payment in both systems after the first sync. Confirm tax, currency, dates, invoice numbers, payment status, and customer names before relying on synced finance reports.

Also compare one edited record. Update a safe field in the system of record, run sync, and confirm the change appears where expected without creating a duplicate.

Review Runs and Webhooks

Open the app detail panel to review recent runs and errors. Provider webhook events can trigger targeted imports when QuickBooks or Xero sends supported record changes.

If webhook updates are enabled, still review periodic run history. Webhooks help with timely changes, but run history is where admins can see failures, authorization issues, and provider payload problems.

Troubleshooting

If OAuth fails, confirm the provider account has permission to connect apps and that popups or redirects are not blocked.

If records duplicate, pause sync and compare names, emails, external IDs, and provider IDs before running another import.

If taxes look wrong, review tax labels and rates in both systems. Accounting providers often require exact tax configuration rather than free-form labels.

If webhook updates stop arriving, reconnect the provider and check the app run history for authorization or payload errors.

If accounting is the system of record, do not bulk edit synced finance records in Agiled until you know which fields will be overwritten by the next sync.

Before Month-end Close

Before using synced data for month-end review:

confirm the accounting tenant is still connected
review recent failed runs or webhook errors
compare a sample of invoices and payments
check tax and currency fields on recent records
pause cleanup imports until finance review is complete

QuickBooks and Xero