How to integrate with Xero: One object sends events, the other nine you poll

Xero is a cloud accounting platform for small businesses and accounting practices, strongest in the UK, Australia, New Zealand, the USA and Canada. The API is well documented and predictable. What decides your build is not the surface, it is how many customers you are allowed to attach to it.

The app is registered by you, in your name, and it is the app that carries the connection budget. If you want the registration steps, the object matrix and the partner tiers in one place, that is the Xero API page. What follows is what the platform does once you are connected.

A connection is a link between your app and one tenant, created per unique user and tenant pair. For the limit, though, Xero counts tenants rather than pairs. Their example: three users on one organisation and one user on another are four connections and two against your ceiling.

Connections then stay alive on their own. Xero keeps them “active indefinitely even if no API calls are being made or if the access token expires”, and only six named events remove one: the user disconnects in Xero, the user loses permission, you delete it through the connections endpoint, the token is revoked, the tenant is deleted or you delete your app.

A tenant ID travels with every single request, and Maesn resolves it at authentication and attaches it afterwards. Xero also needs no environment or company picker, so it runs the plain consent flow rather than the interactive one that Business Central and the DATEV systems use.

Xero access tokens live 30 minutes and refresh tokens 60 days. That much is widely known. The part that costs people a customer is what happens when a refresh goes wrong.

Every refresh returns a new access token and a new refresh token, and you have to persist both. If the response never reaches you, Xero keeps the old refresh token usable for a while, and that window is short and finite.

So the failure mode is not an expired token, it is a lost write. A process that crashes between receiving the new pair and storing it has half an hour to notice, and after that the only fix is a human clicking through consent again. That is why the refresh cycle is the first thing worth moving out of your own deployment path.

Through Maesn the cycle runs per connected organisation on our side, and what your code holds instead is an account key. How that generalises across systems that all expire differently is unified authentication.

One detail to keep even if you never touch OAuth again: the offline_access scope is not optional. Xero requires it for certification, and without it a connection cannot outlive the first 30 minutes.

This is the sentence the rest of the architecture follows from. Through Maesn, Xero exposes ten readable objects, and exactly one of them announces its own changes: invoices. The second event category, contacts, sits on an object that has no read path at all.

That combination is not a quirk of one matrix row. Across all 30+ systems we support, eleven objects send events without being readable by default, and ten of those are marked available on request. Xero’s contacts is the only one where the read simply is not there.

The reason is that Xero keeps one contact record with flags on it, while the unified model splits the read into customers and suppliers. Fourteen of the 30+ systems draw that same line, so the split itself is ordinary. Xero is the only one of them that also fires an event on the combined name.

Two practical consequences. Archiving is not a delete: Xero folds it into update, “including when contacts are archived”, and there are no delete events at all. And the payload you receive is normalised, which is where the system-by-system differences become visible as empty fields rather than as branching code.

Xero delivers webhooks to the app rather than to the customer, so one endpoint receives events for every organisation connected to you. Before it receives anything, it has to pass a validation Xero calls intent to receive, and the rules are unusually specific.

The 401 is the part that trips people, because it is the one response this endpoint has to get wrong on purpose. Xero validates that you reject forgeries before it trusts you with real ones, and an endpoint that cheerfully answers 200 to everything never leaves the validation state.

What happens after a failure is more forgiving than most platforms. Xero retries immediately, then every 15 minutes for up to 24 hours, then disables the subscription and emails the collaborators on your app. Events that occurred meanwhile are held for 31 days and replayed “in order” once you are healthy again.

Which is exactly why Xero also writes that consumers “must ensure they implement idempotency logic and support message replayability”. A replay of 31 days of events is a feature only if the second delivery of an event changes nothing.

Nine of the ten readable objects never tell you they changed. Accounts, booking proposals, customers, expenses, invoice lines, journal entries, suppliers, tax rates and users are all things you have to ask about, and Xero meters the asking.

Xero prices polling itself, and the figure is theirs: “if your rate limit is 5000 calls per day per organisation and you poll just one endpoint every 5 minutes for a single organisation, you’ll burn through 288 calls per day”. They add that excessive polling is “the most common cause of exceeding limits and being temporarily blocked”.

Put the two numbers together and the day has a shape. Nine objects at five-minute intervals is 2.592 calls, more than half the budget, spent before a single record has been read or a single invoice written.

The documented answer to a polling budget is to ask smaller questions. If-Modified-Since takes a UTC timestamp accurate to the second and returns only what changed, and Xero supports it on fourteen endpoints including invoices, contacts, payments, journals and purchase orders.

It is the right tool. It also has a hole in it, and the useful thing is that Xero says so on the same page rather than leaving you to find out.

Read that list against what a finance product actually watches. A moved DueDate is the single most important field in dunning, and a partially paid invoice is exactly the case where it moves. SentToContact decides whether a reminder has gone out. IsSupplier and IsCustomer decide which side of the ledger a company belongs on.

None of those are edge cases, and none of them are covered by the two event categories either. So the honest architecture on Xero is three-legged: events where they exist, delta queries for the bulk, and a slower full pass for the fields the delta query is documented to miss.

Paging is the pleasant part by comparison. Nine endpoints support it, the default page size is 100 and the maximum 1.000, and out-of-range values are clamped rather than rejected.

The response carries a pagination object with pageCount and itemCount, so you no longer fetch until a page comes back empty. Everything else returns its whole set at once, which is two retrieval strategies in one interface and precisely the difference unified pagination and filtering removes.

Writing to Xero is where a shared data model earns its keep, because three of its conventions are the opposite of what a REST client expects. The first is the verbs. Xero, verbatim: “A PUT method will create new data in Xero, whereas a POST will either create new data or update existing data”.

The second is bulk. You can submit many entities in one call, which is how you stay inside the daily budget, and Xero recommends batches of about 50. But the flag that makes bulk usable also changes what a status code means.

So a green status code proves the request was accepted and nothing about whether the records landed. Xero is also blunt about the middle state: “Do not suppress or ignore warnings”, because a warning means the write succeeded while the data may still be wrong, and wrong data in a ledger is a reporting problem later rather than an error now.

The third convention is the good one. Xero has real idempotency: an Idempotency-Key header on POST, PUT and PATCH, ignored elsewhere, with the first response cached and returned for repeats. The window is six minutes from the first call, so it covers a transient network retry and deliberately not a nightly rerun.

We absorb the shape of the integration, not the rules of the platform. Four things stay with you, and it is cheaper to know that now than after the first customer call.

• The rate limit still reaches you. Only Maesn’s asynchronous endpoints absorb bursts, so Xero’s 429 arrives in your code and the backoff is yours. What the asynchronous path does and does not cover is asynchronous processing.
• The read after a contact event is a decision. We hand you the event with its resource id. Because contacts has no read of its own, choosing customers or suppliers depends on what that record is in your product, and only you know that.
• The app is yours, so the tier is yours. You register it in Xero’s developer portal under your product name, which is the name on your customer’s consent screen, and the connection ceiling and certification belong to that app. We run the partner process with you and we cannot hold it for you.
• Deletes do not exist here. No object on this system has delete enabled and Xero sends no delete events, so corrections are posted as new documents. Build that path rather than planning around it.