Connect Xero

Xero is cloud accounting. It holds an organization's contacts, invoices and bills, bank transactions, chart of accounts and reports, and in Australia, New Zealand and the United Kingdom it also runs payroll. Many MSPs keep their own books in Xero, and an MSP that does bookkeeping for clients keeps each client's books as a separate Xero organization. StackJack talks to Xero through the same developer interface Xero publishes for integrations.

Connecting Xero to StackJack gives your AI assistant a family of xero_ MCP tools. MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:

• Answer money questions from the books: profit and loss, balance sheet, trial balance, aged receivables and payables, bank summary, budget summary and the tax reports
• See who owes what by reading invoices, bills, credit notes, quotes, repeating invoices, payments, prepayments and overpayments, and the contacts behind them
• Look up the reference data every entry needs: the chart of accounts, tax rates, tracking categories, currencies, items, branding themes and the organization record itself
• Follow the cash through bank transactions, bank transfers and batch payments
• Check purchasing and the ledger: purchase orders, expense claims, receipts and manual journals
• Read the history and attachments of almost any record, and get a short-lived link to download an attached file or a document PDF
• Look at fixed assets, the file library and projects with their tasks and time entries
• Read payroll for the Australia, New Zealand and United Kingdom payroll products: employees, leave, pay runs, payslips, timesheets, pay items, super and settings

It can also make changes, on the Pro tier:

• Raise and change the paperwork: create invoices, bills, credit notes, quotes, repeating invoices and purchase orders, and update, void or delete them
• Record and allocate money: payments, batch payments, prepayment and overpayment allocations, credit note allocations, bank transactions, bank transfers and manual journals
• Keep the books tidy: contacts and contact groups, accounts, tax rates, tracking categories and options, items, currencies and linked transactions
• Attach files and add history notes to records, and upload to the file library
• Run projects: create projects, tasks and time entries
• Look after payroll: create and change employees, leave, pay items, timesheets and pay runs, and approve timesheets and leave

Reading is free. Every change needs the Pro tier. Anything that records money, deletes, voids, emails, replaces an attachment or changes how an employee is paid is labelled, so your AI assistant asks before running it.

Before you start: what Xero needs from you

StackJack connects to Xero through a Custom Connection, which is the way Xero offers for a connection that belongs to one organization. It is the route Xero itself recommends for AI clients. Three things have to be true first:

• The organization is in Australia, New Zealand, the United Kingdom or the United States. Xero offers Custom Connections only in those four countries. For an organization anywhere else this connector cannot be used.
• The organization has a Custom Connection subscription. Xero charges a small monthly fee per connection, paid by the organization. Any user with the Standard, Advisor or Administrator role and the Connected Apps permission can buy it. Xero's own Demo Company is free, which makes it a safe place to try the connection first. Check Xero's current pricing before you buy.
• A user of that organization approves the connection by email. You name this person, the authorizing user, when you create the Custom Connection. Xero emails them, and the Client ID and Client Secret only appear once they have approved.

One Custom Connection covers exactly one organization. If you look after several organizations, create one Custom Connection for each and add each to StackJack as its own connection. A Custom Connection also cannot reach Xero Practice Manager or Xero HQ, which are separate Xero products.

How StackJack authenticates to Xero

Xero gives you a Client ID and a Client Secret for the Custom Connection, and you also choose which scopes it may use. You paste all three into StackJack.

There is no web address to enter. Xero runs one shared service for every customer, and StackJack finds your organization by asking Xero which organization the Custom Connection is authorized for. You never type an organization ID, and a tool call that needs one uses the connection's own.

Behind the scenes StackJack exchanges the Client ID and Secret for an access key that lasts about thirty minutes, and fetches a new one on its own when it runs out. There is nothing to renew or rotate on a schedule.

The Scopes box has to match what you ticked

Xero decides what a Custom Connection may do from its scopes, and it refuses to issue a token that asks for a scope the connection was not granted. So the list in the StackJack form and the list you ticked in Xero's developer portal have to agree.

The Scopes box opens pre-filled with the scopes for every area StackJack covers, payroll included. If you ticked fewer, remove the ones you did not tick before you save. This is the most common reason a first connection test fails, and the error says so.

Most scopes come in two forms. The plain scope lets the connection read and change, and the form ending in .read lets it read only. To keep your AI read-only whatever tools are switched on, tick the .read forms in Xero and list the same .read scopes in StackJack.

Expense claims and receipts are not listed under any of Xero's current scopes. Xero's own scopes page lists them only under the older broad transactions scope, so whether a connection created with the newer scopes can reach them is not documented. The tools are included and report plainly if Xero refuses them.

Steps

1. Check the organization is in Australia, New Zealand, the United Kingdom or the United States, and that it has, or will buy, a Custom Connection subscription.
2. Create the Custom Connection. Sign in to the Xero developer portal, open My Apps, choose New App and pick Custom connection as the integration type.
3. Tick the scopes and name the authorizing user. Use the table above. Keep a copy of the list: you paste it into StackJack.
4. Have the authorizing user approve it. Xero emails them a link. They choose the organization and approve. You are emailed when it is done.
5. Copy the Client ID and generate the Client Secret. Open the app's details page in the developer portal. Xero shows the secret once, so copy it straight away and treat it as a password. Generating a new one replaces the old one.
6. Enter the details in StackJack. Open Connectors, choose Xero, paste the Client ID and Client Secret, and edit the Scopes box so it lists exactly the scopes you ticked.
7. Run a Test Connection. If it reports a scope error, the Scopes box lists something you did not tick. If it reports a client error, the Client ID or Client Secret is wrong, or the secret was regenerated.

What to know before your AI uses this connector

Money tools act on real books

Creating or changing invoices, bills, credit notes, payments, bank transactions, manual journals, purchase orders and expense claims, and creating a pay run, can post to the ledger and change balances and reports. Your AI assistant is asked to confirm each of them.

Some payroll changes decide what staff are paid, and they are confirmed the same way: setting the bank accounts an employee is paid into, rewriting a payslip's lines, and updating a timesheet in a way that approves it. Check account details with the employee before your AI sets them. Replacing an attachment overwrites the file already stored under that name, so keep a copy first.

Reading the books changes nothing, but it does return your customers' and staff's financial detail, so grant the reads deliberately.

Emailing an invoice sends a real email. It goes to the contact's primary address and any contact people flagged to receive invoices, and it comes from the user who authorized the Custom Connection. It cannot be recalled. Xero limits how many a day each organization can send, and an organization on a trial or the Demo Company can send few or none.

An update can delete what you leave out

When Xero updates an invoice, bill, credit note, quote, purchase order, bank transaction or manual journal, any line item that is not in the request is deleted. An update to a contact deletes any contact person that is not included. Every update tool says so in its description. Ask your AI assistant to read the record first and send back everything it wants to keep.

When a record includes its contact, send only the contact's ID. Any other contact detail in the request updates the contact record itself.

Deleting is usually an update

In Xero the way to delete or void most things is to update them with a status of deleted or voided, so the label on a tool is a better guide than its name. StackJack marks a tool destructive from what it can do, not from how it is called.

Retries and duplicates

In Xero's accounting service a write can create or update, so repeating a create makes a duplicate. StackJack sends a fresh unique key with every write and never repeats a write on its own, so a transient failure cannot double-post an invoice. If a write times out, read the record to see whether it landed before you ask for it again.

Pages, dates and where filters

Lists come back one page at a time. Ask for a page (numbered from 1) to get complete records: Xero's unpaged accounting lists return a lighter summary of each record. The page size is capped at each Xero service's own limit: 1000 for most lists, 500 for projects and 100 for the file library.

Dates in Xero's answers look like /Date(1439434356790+0000)/, which is milliseconds since 1 January 1970 UTC. When you send a date, use YYYY-MM-DD.

A where filter is sent exactly as written, so write it plainly, for example Status=="AUTHORISED", and let StackJack do the encoding.

Payroll is three different products

Xero runs separate payroll products for Australia, New Zealand and the United Kingdom, and each only answers for an organization in its own country. A payroll tool says which country it belongs to, and it is refused for an organization anywhere else. Payroll data carries employee names, tax numbers, bank accounts and pay. Employee and bank detail reads are not recorded or stored by StackJack, and an oversized result is refused rather than saved. Leave the payroll scopes out of the Scopes box if you do not want an AI assistant near them.

Files come back as links

Attachments, document PDFs and library files are not sent inline. StackJack stores the file and gives your AI a read-only download link that works for thirty minutes, together with its type, size and exact expiry. Uploads take the file as base64 or as a public https link, up to 25 MB.

Limits

Xero limits each organization to 60 calls a minute and 5 at the same moment, plus a daily total (1,000 or 5,000 depending on the app). StackJack paces itself below the per-minute limit and tells you plainly when Xero says the day's limit is used up, because retrying cannot help until it resets in UTC. Ask for larger pages and use filters rather than many small reads. If several connections point at different organizations, they share StackJack's pacing for your account, so a very wide sweep across several organizations can run slower than one organization alone.

If an organization is offline or Xero is down for maintenance, Xero answers that it is unavailable. That is not a problem with the credentials and does not count against them. Try again in about five minutes.

Plans and limits

Every read is available on the Free tier. Every change needs Pro. Business reaches the same tools as Pro and differs by monthly call quota.

See the generated Xero tool reference for the current inventory, plan assignment, input schemas, and destructive-action labels. See also Retrying a failed or timed-out write.

Several organizations

One Custom Connection covers one organization. If you look after several, add one connection per organization from the connector's card, name each after the organization, and your AI names it on each call. Omit the name and the call runs against your default connection. Pin an endpoint to one connection when an AI should never reach past a single organization.

See Several connections of one connector.

Troubleshooting

"Xero refused the scopes listed on this connection": the Scopes box lists something the Custom Connection was not granted. Open the connector's settings, remove every scope you did not tick in Xero, and save. If you later add a scope to the Custom Connection in Xero, add it here too.

"Xero did not accept the Client ID and Client Secret": check the pair on the Custom Connection's details page. If the secret was regenerated, paste the new one in. Also check the connection is still authorized: if the authorizing user never approved Xero's email, or the organization's Custom Connection subscription lapsed, Xero refuses the pair.

"Xero accepted the credentials but lists no organization for this Custom Connection": the connection is not authorized for an organization yet, or its subscription has lapsed. Ask the authorizing user to approve Xero's email and check the subscription in Xero's Connected apps settings. This is not counted as a failed credential, and it recovers on its own once Xero lists the organization.

One area is refused while the rest work: the Custom Connection was not granted the scope that area needs, or the organization's Xero plan or role does not include it. A payroll tool is also refused for an organization outside its own country. Tick the scope in Xero, then add it to the Scopes box in StackJack.

A list looks like it is missing detail: ask for a page. Xero's unpaged accounting lists return summaries.

"Xero's daily API limit for this organization has been reached": Xero allows a fixed number of calls a day for each organization and refuses every call after that until the day resets in UTC. Retrying now will not help. Ask for fewer, larger pages and narrower filters, or wait for the reset.

A write timed out: read the record first. Xero may have saved it, and repeating a create makes a duplicate.

Everything worked and then stopped: a Custom Connection can be removed or its subscription canceled in Xero at any time. Open it in the developer portal, check it is still authorized, and re-enter the Client ID and Client Secret.

Xero tools

xero_ · 450 tools · Free 235 · Pro 215

Branding themes

Budgets

Chart of accounts

Connections

Currencies

Invoice reminders

Organization

Organization setup

Tax rates

Tracking categories

Users

Reports

Contact groups

Contacts

Credit notes

Invoices

Items

Linked transactions

Quotes

Repeating invoices

Batch payments

Overpayments

Payments

Prepayments

Bank transactions

Bank transfers

Expense claims

Purchase orders

Receipts

Manual journals

Asset settings

Asset types

Assets

Associations

Files

Folders

Inbox

Project tasks

Project time entries

Projects

Payroll AU: Calendars

Payroll AU: Employees

Payroll AU: Leave applications

Payroll AU: Pay items

Payroll AU: Pay runs

Payroll AU: Payslips

Payroll AU: Settings

Payroll AU: Super fund products

Payroll AU: Super funds

Payroll AU: Timesheets

Payroll NZ: Deductions

Payroll NZ: Earnings rates

Payroll NZ: Employee leave

Payroll NZ: Employee tax

Payroll NZ: Employees

Payroll NZ: Employment

Payroll NZ: Leave types

Payroll NZ: Opening balances

Payroll NZ: Pay run calendars

Payroll NZ: Pay runs

Payroll NZ: Pay templates

Payroll NZ: Payment methods

Payroll NZ: Payslips

Payroll NZ: Reimbursements

Payroll NZ: Salary and wages

Payroll NZ: Settings

Payroll NZ: Statutory deductions

Payroll NZ: Superannuations

Payroll NZ: Timesheets

Payroll NZ: Working patterns

Payroll UK: Benefits

Payroll UK: Deductions

Payroll UK: Earnings orders

Payroll UK: Earnings rates

Payroll UK: Employee leave

Payroll UK: Employee tax

Payroll UK: Employees

Payroll UK: Employment

Payroll UK: Leave types

Payroll UK: Opening balances

Payroll UK: Pay run calendars

Payroll UK: Pay runs

Payroll UK: Pay templates

Payroll UK: Payment methods

Payroll UK: Payslips

Payroll UK: Reimbursements

Payroll UK: Salary and wages

Payroll UK: Settings

Payroll UK: Statutory leave

Payroll UK: Timesheets