QuickBooks Online
Complete guide to QuickBooks Online integration
Complete guide to integrating SettleWise with QuickBooks Online.
Overview
SettleWise syncs automatically with QuickBooks Online to keep your accounting up to date. Once connected, customers, invoices, payments, and credits flow between the two systems in real time — no manual exports or data entry needed.
What Syncs
| Data | Direction | Details |
|---|---|---|
| Customers | Bi-directional | Name, email, phone, address. New customers in either system sync to the other. |
| Invoices | Bi-directional | Invoice creation, status changes, line item updates, and payment allocations sync both ways. |
| Payments | Bi-directional | Payment types, methods, dates, and invoice allocations sync both ways. |
| Credit Memos | Bi-directional | Credits, refunds, rollovers, and credit applications sync both ways. |
Each system owns the entities it creates. Only the owner can delete — an invoice created in SettleWise can only be deleted from SettleWise, and vice versa.
Setup
See QuickBooks Connection for the complete OAuth setup walkthrough with the video guide.
Field Mapping
SettleWise maps its data to QuickBooks fields as follows:
| SettleWise Field | QuickBooks Field |
|---|---|
| Customer Name | Customer Display Name |
| Customer Email | Primary Email |
| Invoice Number | Doc Number |
| Invoice Amount | Total Amount |
| Invoice Due Date | Due Date |
| Payment Amount | Payment Amount |
| Payment Method | Payment Method Ref |
| Payment Date | Txn Date |
| Credit Memo Amount | Credit Memo Total |
Sync Behavior
- Real-time: Changes sync within seconds of being made in SettleWise
- Automatic: No manual "sync" button needed — all changes push automatically
- Reliable: Built-in retry logic handles temporary QuickBooks API outages
- Idempotent: Re-syncing the same data doesn't create duplicates
All entity types sync bi-directionally. Each system owns the entities it creates — only the creator can delete them.
Troubleshooting
Connection Expired
QuickBooks OAuth tokens expire periodically. If sync stops working:
- Go to Settings → Organization → QuickBooks Integration
- Click Reconnect to re-authorize
- Follow the QuickBooks login flow
- Sync resumes automatically once reconnected
Duplicate Customers
If a customer exists in both systems before connecting, SettleWise attempts to match by name and email. Unmatched duplicates may need manual merging:
- Identify the duplicate in the sync history
- Merge the customers in QuickBooks
- Re-sync to update the mapping
Sync Errors
Common sync errors and solutions:
| Error | Cause | Solution |
|---|---|---|
| Auth expired | OAuth token expired | Reconnect QuickBooks in Settings |
| Duplicate name | Customer name already exists in QB | Merge or rename the customer |
| Invalid account | Mapped account deleted in QB | Update account mapping in Settings |
| Rate limited | Too many API calls | Wait 5 minutes; sync retries automatically |
Sync Conflict Resolution
When the same customer is updated in both systems simultaneously:
- Last-write wins for simple fields (name, email, phone)
- SettleWise is the source of truth for invoices and payments
- QuickBooks is the source of truth for chart of accounts and tax settings