In this article
A booking platform founder reaches out to us with a specific problem: every invoice their software generates has to be re-typed into Xero by a bookkeeper at the end of each week. The software works. The accounting doesn’t talk to it. This is one of the most common requests we see on custom software projects: not “build us an accounting system,” but “connect what we already built to the accounting system our finance person actually uses.”
Xero shows up in that conversation more often in the US than most people expect, especially among software companies, professional services firms, and businesses with international operations. This guide covers what the Xero API actually lets you build, where it fits next to QuickBooks and NetSuite, and what a real integration project costs and takes to ship.
Where Xero Fits in the US Accounting Stack
QuickBooks is typically cited as the most common accounting platform among small businesses in the US; exact market-share figures vary across sources, so treat any specific percentage with caution. NetSuite tends to take over once a business grows past a single entity, needs consolidated reporting across subsidiaries, or outgrows QuickBooks’ transaction limits. Xero sits in a different spot: it’s the platform businesses pick when they were built API-first from day one, when they operate in more than one currency, or when the founding team came from outside the US and brought their accounting software with them.
Xero was built in New Zealand and entered the US market directly, rather than growing out of a desktop product the way QuickBooks did. That history shows in the product: multi-currency support is native rather than bolted on, and the API was designed to be used by third-party software from the start, not added later as an afterthought. If your customer base includes companies with cross-border billing, or your own product serves agencies and consultancies managing client books, Xero tends to come up more than it would in a pure domestic-retail context.
How the Xero API Actually Works
Xero authenticates every integration through OAuth 2.0. There are two practical paths, and picking the wrong one early costs weeks later.
Custom Connections are built for a single organization: your own company, or a single client’s Xero account that you’re integrating with internally built software. No app review, no public listing, a faster path to production.
Standard OAuth2 apps are built for software that connects to many different customers’ Xero accounts, the pattern you need if you’re selling SaaS and each customer brings their own Xero organization. These go through Xero’s app review process before they can request production-level scopes, and that review adds real calendar time to a launch plan.
A few mechanics worth planning around before a single line of code gets written:
- Access tokens last 30 minutes. Refresh tokens last 60 days and rotate on each use, so your system needs a reliable job to refresh and store them: losing a refresh token means re-authorizing with the client, not a quiet background fix.
- Scopes are granular:
accounting.transactions,accounting.contacts,accounting.settings, andoffline_access(required to get a refresh token at all) are the ones most invoice-and-payment integrations need. Request the minimum set; broader scopes slow down app review and give your software access it doesn’t use. - Rate limits, per Xero’s own developer documentation, run around 60 calls per minute and roughly 5,000 per day for each connected organization. That’s generous for invoice sync but tight if you’re pulling full transaction history on a schedule, so batch and cache rather than polling on every page load.
- Webhooks push notifications when invoices, contacts, or payments change on the Xero side, which is the only sane way to keep a two-way sync current without constant polling.
Data You Can Actually Sync
| Xero object | Typical use in custom software | What it doesn’t do |
|---|---|---|
Contacts |
Push customer/vendor records from your CRM or app so invoices attach to the right party |
Doesn’t merge duplicate contacts automatically, your system needs matching logic |
Invoices & Credit Notes |
Generate invoices from orders, subscriptions, or bookings directly in Xero |
No native support for complex multi-entity consolidation inside one organization |
Bank Transactions & Payments |
Mark invoices paid, reconcile against bank feeds or payment processor events |
Doesn’t capture chargebacks or disputes on its own, that logic lives on your side |
Items & Inventory |
Sync a product catalog so line items carry consistent pricing and tax codes |
Basic inventory tracking only; not a warehouse management system |
Reports (P&L, Aged Receivables) |
Pull live financial data into a client-facing dashboard |
Read-only, and formatted for accounting use, not built for arbitrary BI queries |
Tracking Categories |
Tag transactions by department, location, or project for custom reporting |
Limited to two active categories per organization |
The gap people hit most often: Xero expects one organization to represent one set of books. If your software serves a franchise or multi-location business that wants consolidated reporting across several Xero organizations, that consolidation logic has to live in your integration layer. Xero won’t do it for you.
Integration Patterns We’ve Built
The shape of a Xero integration almost always maps to one of three patterns, and most projects end up combining two of them.
One-way push. Your software is the source of truth for orders or bookings; it creates invoices and contacts in Xero and never reads anything back. This is the fastest build and the one most SaaS billing integrations start with.
Two-way sync with reconciliation. Payments collected in your app need to show up as paid invoices in Xero, and changes made directly in Xero (a manual adjustment, a refund) need to flow back. This is where webhook handling and conflict resolution matter: what happens if both sides edit the same invoice.
Reporting pull. Your software reads P&L or receivables data from Xero to populate a client dashboard, without writing anything back at all. Lower risk, since a bad sync can’t corrupt the client’s books, but it needs careful caching given the rate limits above.
We’ve built this exact shape of problem before, outside the Xero ecosystem specifically. On one ERP project for a transportation company, dispatch records, fleet data, and financial documents lived in three disconnected places (a GPS tracking tool, spreadsheets, and a separate accounting system), and nobody had a single view of the business. We built one system where trip completions, driver payouts, and closing documents flowed automatically into the financial side instead of being manually re-keyed between departments. On a separate project, a lending business needed its customer-facing portal to reflect real-time payment status from a banking payment gateway, instead of staff checking a separate system by hand every morning. Both projects are the same underlying problem a Xero integration solves: data that’s correct in one system but stuck there, instead of flowing to where decisions actually get made.
Payments and Reconciliation
Most US businesses integrating Xero are also handling payments somewhere in the same flow, and that’s where reconciliation gets real. ACH and Same Day ACH cover B2B invoicing where a wire fee isn’t worth it; Stripe and card processing cover subscriptions and faster-turnaround retail transactions. The reconciliation sequence that actually works in production looks like this: a payment event fires from Stripe or your bank’s ACH processor, your system matches it to the open Xero invoice by amount and reference, marks the invoice paid through the Xero API, and logs the match in an audit trail your finance team can review later.
Refunds and disputes need separate handling. Xero’s payment object doesn’t automatically track a chargeback that happens three weeks after the original payment, so that logic has to live in your own system, with a clear record of what triggered the reversal and when it was applied to the books.
Sales Tax Nexus: Not Something to Bolt On Later
If your software calculates or invoices sales tax across state lines, build the nexus question into the project plan before writing integration code, not after. Since the Supreme Court’s 2018 decision in South Dakota v. Wayfair, Inc., states can require sales tax collection based on economic activity rather than physical presence. A threshold of $100,000 in sales or 200 transactions gets cited often as the general pattern, but it isn’t universal: individual states set their own numbers, and several have dropped the transaction-count test entirely in recent years. This isn’t tax advice, and nexus rules change state by state; check current thresholds with an accountant or a dedicated sales-tax service before an invoicing integration goes live across multiple states.
Customer Data Moving Between Systems
A Xero integration almost always means customer names, addresses, and payment details moving between your software, Xero, and a payment processor. For businesses with California customers, that triggers CCPA/CPRA obligations: knowing what data moves where (a simple data map covering your app, Xero, and the payment gateway), honoring access and deletion requests across all three systems rather than just your own database, and keeping vendor contracts with Xero and your payment processor current on data-handling terms. None of this is exotic, but it has to be designed into the integration from the start. Retrofitting a deletion workflow after three systems already hold a customer’s invoice history is a much bigger job than building it in from day one.
Planning the Project: Cost and Timeline
Pricing below reflects general ranges for this kind of work and what’s typically included at each tier; treat it as a planning reference, not a quote. The real number depends on how many Xero objects you’re syncing and whether payments are part of the scope.
| Scope | What’s included | What’s usually extra | Typical range |
|---|---|---|---|
One-way invoice sync |
OAuth setup, contact + invoice push, basic error logging |
Payment reconciliation, reporting, multi-org support |
$3,300–$6,500 (≈£2,600–£5,100) |
Two-way sync with reconciliation |
Everything above, plus webhook handling, payment matching, conflict resolution |
Multi-entity consolidation, custom tax logic |
$8,000–$18,000 (≈£6,300–£14,100) |
Multi-tenant / enterprise (NetSuite-adjacent complexity) |
Public OAuth app, Xero app review support, multi-org reporting, audit trail |
Ongoing app-store maintenance, new Xero API version migrations |
$20,000+ (≈£15,800+) |
At Pazl, fixed-price projects in this general range start around $3,300–$6,500 (≈£2,600–£5,100), with the exact price locked into the contract once the scope is defined: which Xero objects sync, in which direction, with or without payment reconciliation. Every project ships with a six-month warranty on the code we deliver, and we run a demo each week so you see the integration working before it’s finished, not just at handoff.
FAQ
Does our Xero integration need to go through Xero’s app review process? Only if you’re building a public app that connects to many different customers’ Xero organizations. If you’re integrating your own company’s software with a single Xero account (yours, or one client’s), a Custom Connection skips the review entirely and gets to production faster.
What do you need from us before starting? A Xero account (demo or sandbox organization works for development), a clear answer on which direction data flows (push only, or two-way), and whoever owns your payment processing if reconciliation is part of the scope. If sales tax across multiple states is involved, loop in your accountant early rather than after the integration is built.
Does this replace our bookkeeper? No. It removes the manual re-entry between your software and Xero, but someone still needs to review the books, handle exceptions, and make judgment calls on anything that doesn’t match automatically. The integration cuts the repetitive work, not the oversight.
What happens if Xero changes its API? Xero versions its API and gives advance notice before deprecating endpoints, but any integration needs someone watching for those changes rather than assuming it’ll keep working forever. This is normal maintenance, not a sign the original build was done wrong.
How long does a basic sync actually take? A one-way invoice push with contact sync is usually the fastest tier to ship, often a few weeks once scope is locked. Two-way sync with reconciliation takes longer because of the conflict-handling logic; plan for it as a separate phase rather than an add-on to the simple version.
Questions about a specific Xero setup, or whether your integration needs a Custom Connection or a public OAuth app, reach out at hello@pazl.ai.



