Xero connector: ask about invoices and cash owed, approve drafts before they exist

This page is for the Xero adviser or finance lead who will link a Xero organisation to OrgRelay. It covers the five tools, the Xero app and scopes, how tenants are chosen, Xero's per-organisation call limits, and which scopes to grant for apps created before and after Xero's 2026 scope change.

#What staff can ask

• "Which bills from Pacific Freight are still awaiting payment?" calls finance.invoices with type: ACCPAY, status: AUTHORISED and customer: Pacific Freight. In Xero, bills are invoices of type ACCPAY, so the same tool covers both sides.
• "How much is overdue right now, and from whom?" calls finance.receivables with overdue_only: true.
• "Give me revenue and net profit for September." calls finance.summary with the month's first and last day.
• "Is Kiwi Outdoor set up as a supplier as well as a customer?" calls customers.search and reads the is_customer and is_supplier flags.
• "Prepare an invoice for Kiwi Outdoor: 40 tents at 129, account 200." calls finance.create_invoice, which waits for approval.

#Tools

Results use the field names from the connector spec. Filters become Xero where clauses. For example, customer turns into Contact.Name.Contains("...") and dates into Date>=DateTime(2026,10,01). Xero pages invoices and contacts in fixed blocks of 100. The connector's cursor is a row offset: it works out which Xero page holds that offset, starts at the right row, and reads into the following page when a request crosses a page boundary. Any limit up to 100 walks the full result without gaps. finance.receivables lists AUTHORISED sales invoices with AmountDue > 0, earliest due date first. With overdue_only, the condition DueDate < today goes into Xero's own where clause, so every page is made of overdue invoices only. The same standard tool names are used for QuickBooks Online, so finance prompts carry over between the two.

#Credentials and scopes

Xero only supports OAuth 2.0 (see authentication for how OrgRelay handles OAuth platforms in general). You create a Web app in the Xero developer portal and enter its credentials:

• Client ID and Client secret, required.
• Organisation (tenant) ID, optional. If it is blank, OrgRelay calls GET /connections and uses the first organisation. After Connect, OrgRelay records the tenant it picked.
• Advanced: API base URL and OAuth base URL, normally unchanged, and Scopes (granular by default, or broad).

OrgRelay runs the authorization code flow with PKCE, and the token request uses HTTP Basic client authentication. Access tokens last 30 minutes. OrgRelay refreshes them about two minutes before expiry and stores the rotated refresh token encrypted, as the security model describes. Requesting offline_access is what gives OrgRelay a refresh token at all. If the connection sits unused long enough for Xero to expire the refresh token, re-authorize from the connection page.

By default the connector requests Xero's granular scopes. Xero's granular scopes FAQ says apps created on or after 2 March 2026 use granular scopes, and older apps may keep the broad ones until September 2027. Granular scope requests require OrgRelay 1.4.0 or later.

The granular names above are the ones Xero's documentation gives for these endpoints. Check them against the scopes enabled on your app before you authorize. If an app created before 2 March 2026 refuses the granular set, change the advanced Scopes field from granular to broad and authorize again.

The Xero user who consents needs the Adviser role, or Standard with the right to manage connected apps.

#Which actions need approval and what the approver sees

finance.create_invoice is the only write. Its approval request lists the contact ID, each line's description, quantity, unit amount and account code, plus the due date and reference.

What the approver should know:

• The invoice is always Type: ACCREC and Status: DRAFT. Xero does not post drafts to the ledger, and they cannot be emailed until they are approved inside Xero. Approving in OrgRelay does not approve the invoice in Xero. Two human checks happen before money is involved.
• When a line has no account_code, the connector uses 200. That is Sales in Xero's default chart of accounts. Organisations with a customised chart should insist on an explicit code.
• Tax uses the account's default tax rate, because the connector does not send a tax type.
• The result returns Xero's invoice number, so the draft is easy to find on the Draft tab of Xero's invoice list.

Approved calls carry the key orgrelay-approval-<approval id>. The human-in-the-loop guide explains how to route this approval to someone outside the requester's own team.

#Set it up

1. Sign in at developer.xero.com with a user who has Adviser rights on the organisation. Open My Apps → New app, choose Web app and name it OrgRelay. A new app gets granular scopes; an existing app created before 2 March 2026 can be reused with the broad setting.
2. Set the redirect URI to the callback OrgRelay shows: your OrgRelay address plus /oauth/callback.
3. Under Configuration, generate a client secret. Copy the client ID and secret.
4. In OrgRelay, go to Admin → Business systems → App directory, choose Xero and enter both values. Add a tenant ID if the authorising user has several organisations.
5. Click Authorize. On Xero's consent screen, pick the organisation and allow access. OrgRelay displays the tenant name once it is connected.
6. Grant the connection to roles and decide who can approve drafts. The quickstart shows how a connection is bound and checked in OrgRelay. If you'd like to try it first, connect Xero's free Demo Company.

#Limits and things it deliberately does not do

• Per-organisation limits. Xero allows 5 concurrent calls, 60 calls per minute and 5,000 calls per day per connected organisation, plus 10,000 calls per minute across the whole app. Xero's pricing page lowers the daily figure to 1,000 per organisation on the free Starter plan, which also allows a maximum of 5 connections. A self-built app connecting one company's own organisation typically sits on Starter, so plan for 1,000 calls a day and upgrade the Xero plan for heavier use.
• OrgRelay's limits sit on top: 120 calls per minute per connection, a 60-second pause after three consecutive failures, and about 12,000 characters of each result shown to the AI. Xero's 60 per minute is the tighter limit, so batch questions sensibly.
• Not exposed: stock and sales orders (those live in an ERP such as Odoo), approving or voiding invoices, payments, bank transactions, manual journals, credit notes, purchase orders, the balance sheet, aged reports by contact, payroll and files. Card payouts and fees are better read from the Stripe connector.
• P&L rows. finance.summary returns Xero's summary rows (totals for income, costs and net profit), not every account line.

#Official MCP server and OrgRelay

Xero offers two MCP options. The open-source Xero MCP server (npm package @xeroapi/xero-mcp-server) runs locally over stdio. Xero also hosts a Remote MCP server at https://api.xero.com/mcp/v1, which authorises through OAuth 2.0 with PKCE. Xero's Remote MCP FAQ says it is included on Core plans and above, Starter apps can use it with the demo organisation only, and Custom Connection apps are not eligible.

Neither plugs into OrgRelay unchanged. OrgRelay's third-party MCP connection speaks Streamable HTTP (see MCP transports) and authenticates with a bearer token or OAuth client credentials. The local server uses stdio and the remote server expects an interactive OAuth sign-in with PKCE, and OrgRelay cannot connect either kind directly. Inside OrgRelay, the connector on this page is the route to Xero, while the vendor servers suit individual users in their own MCP clients.

Through this connector, OrgRelay applies its company-level controls: each tool granted per role, an approval step before any tool that writes, one audit log across Xero and your other systems, and a deployment on the company's own Mac mini. If you call Xero from a desktop client today, the Claude Desktop guide shows how that differs from running it through OrgRelay. The wider comparison is on official MCP servers and enterprise patterns.

#Common questions

Will the Xero connector work with an app I create today? Yes. By default the connector requests Xero's granular scopes (accounting.invoices, accounting.reports.profitandloss.read, accounting.contacts.read, accounting.settings.read plus offline_access), which is what Xero allows for apps created on or after 2 March 2026. Older apps can switch the advanced Scopes field to broad. This requires OrgRelay 1.4.0 or later.

My login has three Xero organisations. Which one does OrgRelay use? The one whose tenant ID you enter. If the field is blank, OrgRelay uses the first organisation returned by Xero's /connections endpoint for that authorisation. Create one OrgRelay connection per organisation to keep them apart.

Does an approved invoice get sent to the customer? No. finance.create_invoice always creates an ACCREC invoice with status DRAFT. Someone has to approve it in Xero before it posts to the ledger or can be emailed.

#Related

• All connectors
• Odoo connector
• Stripe connector
• Authentication and OAuth
• Security model
• Finance agents on orgrelay.com