QuickBooks & Xero Invoice Sync Without Duplicates
Most invoice sync projects fail the same way: the first version works in the demo, then a network timeout causes a retry, the retry creates a second invoice in QuickBooks or Xero, and the finance team spends Friday deleting duplicates and fixing tax lines by hand.
The problem is rarely the API. It is the missing sync design around it. I run Loop Origin , a software company that builds custom web applications and the integrations behind them. I wrote this with help from AI tools and checked every config and code sample myself.
This guide covers one problem: QuickBooks and Xero invoice sync from a custom platform without duplicates, drift or broken tax.
How do I sync invoices to QuickBooks or Xero without duplicates?
Direct answer: Write each invoice to a local outbox in the same database transaction that creates it, push it with a background job that sends an idempotency key (QuickBooks Online's requestid, Xero's Idempotency-Key header), store the returned external ID in a mapping table, and update instead of create once a mapping exists. Reconcile nightly.
Who this is for
This is for CTOs and operations leads running a custom storefront, ERP, booking platform or B2B portal that issues invoices, while finance lives in QuickBooks Online or Xero.
If you invoice a few dozen times a month, a native app connector may be enough. Once you have custom pricing, multiple tax regions, credit notes and partial payments, you need a sync you control.
Four ways to get invoices into accounting
| Approach | Duplicate protection | Tax and account mapping | Failure visibility | Ongoing cost driver | Good fit |
|---|---|---|---|---|---|
| Manual CSV import | Human checks | Manual each time | None until month-end | Staff hours | Very low volume |
| iPaaS recipe (Zapier, Make) | Limited; retries can duplicate | Basic field mapping | Task history per run | Per-task pricing as volume grows | Simple, standard invoices |
| Marketplace connector app | Vendor-defined | Vendor's fixed model | Vendor dashboard | Per-seat or per-order fees | Standard platforms like Shopify |
| Direct API sync (outbox + jobs) | Idempotency keys + mapping table | Full control per line | Your own logs and alerts | Engineering time to build and maintain | Custom pricing, multi-region tax, high volume |
I am not quoting prices here because they change and depend on plan and volume. The trade-off is structural: connectors are cheaper to start but you inherit their data model; a direct sync costs engineering time but fits your business rules.
The architecture I use
Order / invoice created | [DB transaction] ---> invoices table | ---> accounting_outbox (status=pending) v Queue worker (Laravel job) |-- load mapping (local_id -> external_id) |-- build payload (customer, items, tax codes, accounts) |-- POST create or update with idempotency key |-- save external_id + SyncToken / UpdatedDateUTC v Webhooks from QuickBooks / Xero --> verify signature --> mark drift v Nightly reconciliation --> compare totals and status --> alert ~~~ Three tables carry the whole design:
- accounting_outbox: one row per pending change, with the payload hash, attempt count and last error.
- accounting_mappings: local entity type and ID to external ID, per connected organization (QuickBooks realm or Xero tenant).
- accounting_connections: OAuth tokens, encrypted, with expiry times and the organization ID.
The outbox matters because it is written in the same transaction as the invoice. If the API is down, the invoice still exists locally and the job retries later. If your app crashes after commit, nothing is lost.
I go deeper on this pattern in Idempotent Jobs & Exactly-Once Effects: Designing Safe Retries.

Image: AI-generated.
Idempotency: the duplicate killer
Both platforms give you a way to make a retried create safe:
- QuickBooks Online accepts a
requestidquery parameter on write requests. Retrying with the samerequestidreturns the original result instead of creating a second record. - Xero accepts an
Idempotency-Keyheader on POST and PUT requests for the same purpose.
The key must be stable for the business event, not random per attempt. I derive it from the outbox row:
final class PushInvoiceToAccounting implements ShouldQueue
{
public int $tries = 8;
public function backoff(): array
{
return [30, 60, 120, 300, 600, 1800, 3600];
}
public function handle(AccountingClient $client): void
{
$row = AccountingOutbox::lockForUpdate()->findOrFail($this->outboxId);
if ($row->status === 'done') {
return;
}
$key = 'inv-'.$row->invoice_id.'-v'.$row->version; // stable per change
$map = AccountingMapping::for($row->connection_id, 'invoice', $row->invoice_id);
$result = $map ? $client->updateInvoice($map->external_id, $row->payload, $key, $map->sync_token) : $client->createInvoice($row->payload, $key);
AccountingMapping::upsertFromResult($row, $result);
$row->markDone($result->externalId);
}
}
The version number changes only when the invoice content changes, so a retry reuses the key while a genuine edit gets a new one. QuickBooks updates also need the current SyncToken; if it is stale you get a conflict, which is a signal to reload and rebuild the payload, not to retry blindly.
Mapping customers, items, tax and accounts
Duplicates are not only about invoices. A sync that creates a new customer for every order fills the ledger with "Ahmed Khan (2)". Map these before you push a single invoice:
| Local entity | QuickBooks Online | Xero | Matching rule I use |
|---|---|---|---|
| Customer | Customer | Contact | Stored mapping first; then exact email; never name-only |
| Product / service | Item | Item (code) | Your SKU stored as item code or name; mapping table wins |
| Tax rate | TaxCode (region-specific) | TaxType per line | Explicit config table per region; fail if missing |
| Revenue account | Income account on Item | AccountCode per line | Config per product category |
| Payment | Payment linked to invoice | Payment against invoice | Push only after the invoice mapping exists |
| Credit note | CreditMemo | Credit note | Linked to the original invoice mapping |
The most important rule in that table is "fail if missing". If a new tax region appears and there is no mapped tax code, the job should stop with a clear error, not fall back to a default that looks right and books the wrong tax.
OAuth tokens and rate limits
Both APIs use OAuth 2.0 with short-lived access tokens and refresh tokens. Xero rotates refresh tokens, so each refresh returns a new one and the old one stops working; QuickBooks may also return a new refresh token. Store the newest token in the same transaction that uses it and serialize refreshes per connection with a lock. Two workers refreshing at once is a classic way to lose the connection and force a finance user to reconnect.
Both platforms enforce per-organization rate limits and concurrency limits. Check the current numbers in their developer docs rather than hard-coding them from a blog post. Practically: run one queue per connected organization with limited concurrency, honor HTTP 429 responses and any Retry-After value, and batch where the API allows it.
Webhooks and drift
Finance teams edit invoices in QuickBooks or Xero. If your platform never hears about it, the two systems drift. Both platforms send webhooks signed with HMAC-SHA256: QuickBooks in the intuit-signature header, Xero in x-xero-signature. Verify the signature against the raw body before parsing, then treat the webhook as a hint: fetch the record and compare.
$expected = base64_encode(hash_hmac('sha256', $request->getContent(), $webhookKey, true));
abort_unless(hash_equals($expected, $request->header('x-xero-signature', '')), 401);
Decide ownership per field. In most of my projects the platform owns line items and prices; accounting owns payment status and posted adjustments. Drift on a platform-owned field raises an alert; drift on an accounting-owned field updates the local record.
Failure modes I have seen
- Retry storms after an outage. Hundreds of jobs wake at once and hit rate limits. Fix: jittered backoff and per-organization queues.
- Rounding differences. Line totals rounded differently from the accounting platform's tax calculation leave a one-cent gap. Fix: send amounts the way the platform expects (tax-inclusive or exclusive) and reconcile totals.
- Deleted in accounting, still mapped locally. Updates then fail forever. Fix: handle "not found" by flagging for review, not by recreating silently.
- Disconnected organization. A refresh token expires after a long idle period. Fix: alert a named owner when a connection fails, and pause the queue instead of burning retries.
- Wrong organization. A user with several Xero tenants connects the wrong one. Fix: show the connected organization name in your admin and require confirmation.
The same discipline applies to any partner API; I covered the wider version in Third-Party API Deprecations: Catch Them Before Prod. If invoices come from a purchasing flow, Three-Way Invoice Matching: Automating AP in Custom ERP shows the payables side.
Rollout checklist
- List every entity to sync: customers, items, invoices, credit notes, payments.
- Build mapping and config tables for tax codes and accounts per region.
- Add the outbox write inside the invoice transaction.
- Implement create and update with stable idempotency keys.
- Encrypt tokens; serialize refreshes per connection.
- Add per-organization queues with backoff and 429 handling.
- Verify webhook signatures on the raw body.
- Write a nightly reconciliation comparing count, totals and status.
- Build an admin screen showing failed rows with a one-click replay.
- Test against the sandbox or demo company with retries forced on purpose.
- Go live for one organization or region first, then widen.
FAQs
Should I sync invoices in real time or in a nightly batch? Near-real-time through a queue is usually better: errors show up while the order is fresh. Keep a nightly reconciliation either way.
Can I use the same code for QuickBooks and Xero? Share the outbox, mapping and retry logic. Keep a separate adapter per platform, because tax, accounts and update semantics differ.
How do I stop duplicate customers in QuickBooks or Xero? Store the external customer ID after the first match and always use it. Match new customers on a stable key like email, never on name alone.
What happens if finance edits an invoice in Xero? A webhook tells you something changed. Fetch the record, compare it to your field ownership rules and either update locally or raise an alert.
Is an iPaaS tool like Zapier good enough? For simple, low-volume invoices, often yes. Once you need multi-region tax, credit notes and guaranteed no duplicates, a direct sync is easier to trust.
How long does a direct sync take to build? It depends on the number of entities, tax regions and edge cases. Scope it after mapping your entities and tax rules, not before.
Wrap-up
A reliable invoice sync is an outbox, a mapping table, stable idempotency keys and a nightly reconciliation. Get those four right and QuickBooks or Xero stop being a source of Friday cleanup. If you want a team to design or review one for your platform, see how we approach Laravel development.
Which part of your accounting sync breaks most often: tax, customers or retries? Tell me in the comments.
Follow & Connect
- LinkedIn: Loop Origin
- X: Muhammad Ali Mughal (@AliMughal887)
- GitHub: Loop Origin (@LoopOrigin)
Watch on YouTube: Resume Boost AI ยท PixelValut ยท Daily AI News By Ali
Comments
No comments yet. Start the discussion.