Xero API: what you can read and write, and what you cannot

By KYN AI Advisory Team — AI implementation specialists, Singapore

The Xero API lets software read and write the core ledger objects: contacts, invoices and bills, payments, credit notes, bank transactions, manual journals and the chart of accounts. It does not file your GST return, it does not replace your accountant's judgement, and it only touches an organisation whose owner has granted your app access. Plan a build around that boundary: let software prepare and post, and keep approval and filing with a person. Confirm each endpoint against Xero's current API reference before you commit, because the reference changes.

What does the Xero API read and write?

Think of the API in three layers.

Read. Software can pull what a report would show: invoices and bills with status, contacts, payments, bank transactions, accounts and tax rates. This supports dashboards, ageing reports, duplicate checks and morning summaries without anyone exporting a spreadsheet.

Write. Software can create and update the same objects: draft an invoice, create a bill from an extracted PDF, record a payment against an invoice, post a manual journal for an accrual. A draft is the safe default. A person reviews the draft in Xero and approves it.

Attach. Files such as the supplier PDF can be attached to the record, so the evidence travels with the entry.

This list is a summary for planning, not a replacement for the reference. Endpoint names and fields move.

What can you not do through the API?

Plan for these limits early. They are the usual surprises.

| You may expect | What to plan instead | |---|---| | Software files the GST return | A person prepares the figures in Xero and submits to IRAS. Software can assemble the workings. | | Software marks bank lines as reconciled | Matching logic can sit outside Xero and suggest matches. Confirm in Xero's reference what the API exposes for statement lines and reconciliation. | | Software approves its own bills | Keep approval with a named person. A bill from software lands as a draft. | | Your app reads every organisation a user owns | Each organisation is a separate connection the user must grant. | | Payroll for Singapore through the same API | Check which payroll APIs Xero offers for your region before you plan around one. |

On bank reconciliation, the practical split is this. Bank feeds bring lines into Xero. Matching those lines to bills and invoices, with a reason for each match, is work you can do outside Xero and present as a suggestion. We compare the two in Xero bank feeds vs automated bank reconciliation and describe the build in automate bank reconciliation in Singapore.

How do scopes work, and what changed in 2026?

A scope is a permission your app asks the user to grant. The user sees the list on the consent screen. Ask for less, and more owners say yes.

Xero is replacing broad scopes with granular ones. Per Xero's granular scopes FAQ:

• Apps created on or after 2 March 2026 use granular scopes.
• Apps created before that date can request granular scopes from April 2026 and can mix broad and granular scopes for now.
• Granular scopes are not applied to existing tokens automatically.
• Xero gives an example: replace the broad accounting.transactions scope with the narrower accounting.invoices scope in the authorisation link.
• All customers need to migrate by September 2027.

For a build, the implication is direct. Request only the objects your agent needs. An agent that drafts bills needs bill and contact access. It does not need payroll or reports. Narrow scopes also limit the damage if a credential leaks.

How should authentication and tokens be handled?

Xero uses OAuth 2.0. The user signs in to Xero, grants your app the listed scopes, and your app receives tokens. Four rules keep this safe:

1. Store tokens in a secrets manager in your cloud account, never in code or a spreadsheet.
2. Refresh tokens on a schedule and alert when a refresh fails. A broken token silently stops every flow built on it.
3. One connection per organisation, with the owner's name recorded against it.
4. Revocation works. The owner can disconnect the app in Xero. Your system should show a clear "disconnected" state and not retry forever.

Your connection is a named, revocable grant. That is also how you want your vendors to hold access to your books.

What about rate limits and volume?

Xero limits how fast an app can call the API, and it returns an error when you exceed the limit. Read the limits in Xero's current developer documentation, because they differ by call type and have changed before. We did not state numbers here because the page could not be confirmed on the check date.

Design for the limit regardless of its value:

• Batch. Send many bills in one call where the API allows it, not one call per bill.
• Back off. On a rate error, wait for the interval the response gives, then retry.
• Be idempotent. Store the supplier and invoice number you have already posted, so a retry never creates a duplicate.
• Page through reads. Pull only records changed since your last run.
• Use events where offered. A notification of change costs fewer calls than polling.

Volume is rarely the problem for an SME. Duplicates are.

What does a safe Xero integration look like?

A pattern that works for a small finance team:

1. Bills arrive in one mailbox. Software extracts supplier, date, amount, currency and tax.
2. Software checks for a duplicate against bills already in Xero.
3. Software creates the bill as a draft with the PDF attached and a note of the source email.
4. A named person reviews and approves in Xero.
5. Software records the action in its own log with the actor and time.
6. Payment stays with a person.

Nothing in this flow sends money or files anything. Every write is a draft. That is the design principle: software prepares, a person decides.

Where KYN fits

KYN builds integrations between your accounting package and the rest of your stack: the inbox, the CRM, the bank and WhatsApp. We design them with narrow scopes, tokens in your cloud account's secrets manager, drafts instead of posts, and a log of every action with the actor. Outbound messages, money, filings and deletions wait for a named person.

The first 14 days are a review of your stack and interviews with your team. A full build ships in under 90 days, in a cloud account in your name, and you can revoke KYN's role while the system keeps running. See integrations and finance systems. For accounting package options, read accounting software for Singapore SMEs compared.

Frequently asked questions

Can an AI agent post to Xero by itself?

Technically yes. We advise against it for anything that affects the ledger. Have the agent create drafts and let a named person approve, so the agent cannot post an error you only find at month end.

Do I need a developer account to use the Xero API?

You register an app in Xero's developer portal, and each Xero organisation owner grants it access. Read Xero's current developer terms for the app tiers and any fees that apply to your use.

Can the API replace my bookkeeper?

No. It removes typing and matching. A bookkeeper or finance lead still reviews exceptions, signs off the close and answers for the GST return.

Checked 30 October 2026.

Curious whether Marketing agents fits your business? Talk to KYN on WhatsApp — no forms, just a conversation.

Start Building →