Xero
Read and write one Xero organisation - contacts, invoices, bills, payments, accounts and items - and run Xero's own financial reports.
Connect a Xero organisation to work its books: list and search contacts, invoices and payments with Xero's own filter expressions, read an invoice in full with its line items, create or update contacts and invoices in batches, record payments, read the chart of accounts and the item catalogue, email an invoice to its contact, and run Xero's reports - profit and loss, balance sheet, trial balance, bank summary and aged receivables or payables. Every write reports its outcome per record, and totals come from Xero's own count rather than from measuring a page.
Connect
Sign in with Xero. Sign in with Xero to read and write the organisations you have access to. An organization admin configures the OAuth app once under Integrations → OAuth apps; after that, connecting is a consent screen.
-
Connecting signs in as YOU - every invoice, contact and payment this integration writes is stamped with your Xero user, and your role in each organisation is the ceiling.
-
Xero's consent screen lets you grant SEVERAL organisations at once. If you grant more than one, set Organisation ID on this connection afterwards (List tenants shows the ids) - otherwise a call would act on whichever Xero happened to list first.
-
Xero refresh tokens rotate on every use and expire after 60 days of inactivity, so a connection nothing has run for two months needs reconnecting.
-
Xero allows 60 API calls per minute and 5,000 per day per organisation. The daily limit does not clear until Xero's own rollover - an automation that exhausts it is stopped for the rest of the day, not for a few seconds.
-
For scheduled or triggered automations, connect a dedicated Xero user and bind the automation as a service connection.
| Setting | Required | What it is |
|---|---|---|
Organisation ID (TENANT_ID) | No | The Xero tenant id every call acts on (List tenants shows the ids). Leave it empty only when the sign-in grants exactly one organisation - with two or more granted, calls refuse until this is set rather than picking one. |
Tools
| Tool | Access | What it does |
|---|---|---|
List tenants (yekar.xero.list-tenants) | Read | The Xero organisations this connection's sign-in can reach, with their tenant ids. One Xero sign-in can grant several organisations at once, and every other tool acts on exactly one of them - so when this returns more than one row, the Organisation ID property on the connection is what decides which. Run this to get the id to put there. |
Get organisation (yekar.xero.get-organisation) | Read | The Xero organisation this connection acts on - its name, base currency, financial year end and whether it is a demo company. The cheapest confirmation that the connection points at the books you think it does, and the place to read the base currency before writing an amount. |
List contacts (yekar.xero.list-contacts) | Read | Customers and suppliers in this Xero organisation, filtered by Xero's own where-expression or a free-text search. Pass a page number to get Xero's real total for the filter (itemCount) alongside the rows; without one Xero returns every match and states no total. |
Upsert contacts (yekar.xero.upsert-contacts) | Write | Create or update customers and suppliers. Xero reads a ContactID as 'update this one' and its absence as 'create', so one call can do both. Sent with summarizeErrors=false: valid contacts are written even when others in the batch are rejected, and the result reports the outcome PER contact - read the counts rather than the absence of an error. An update REPLACES the fields it names; omitted fields keep their stored values. |
List invoices (yekar.xero.list-invoices) | Read | Sales invoices (ACCREC) and bills (ACCPAY) in this organisation, filtered by status, contact, date or Xero's where-expression. Returns SUMMARY invoices - Xero omits line items from lists, so use Get invoice for the detail. Pass a page number to get Xero's own total for the filter alongside the rows. |
Get invoice (yekar.xero.get-invoice) | Read | One invoice in full - line items, tracking categories, payments and credit allocations. This is the only way to see an invoice's lines: List invoices returns a summary view with LineItems omitted, so anything reasoning about what an invoice is FOR has to read it here. |
Upsert invoices (yekar.xero.upsert-invoices) | Write | Create or update sales invoices and bills. Xero reads an InvoiceID as 'update this one' and its absence as 'create'. Sent with summarizeErrors=false, so valid invoices are written even when others in the batch are rejected and the result reports the outcome PER invoice. A DRAFT is not in the ledger; AUTHORISED is. An AUTHORISED invoice with payments against it can no longer be edited - Xero rejects the update rather than silently ignoring it. |
Email invoice (yekar.xero.email-invoice) | Write | Email an AUTHORISED invoice to its contact, using the organisation's own Xero email template and the contact's stored address - this endpoint takes no recipient, subject or body, so what goes out is whatever Xero has on file. The mail leaves immediately and cannot be recalled. Xero rejects the call for a DRAFT invoice or a contact with no email address. |
List accounts (yekar.xero.list-accounts) | Read | The organisation's chart of accounts - every account's code, name, type and tax treatment. Invoice and bill lines reference these by AccountCode, so this is what to read before building one: an invalid code is rejected, and a valid but wrong one posts real money to the wrong place. |
List items (yekar.xero.list-items) | Read | The organisation's products and services, with their sale and purchase details - unit price, account code and tax type. An invoice line referencing an ItemCode inherits those, which is the difference between an invoice that matches the org's own pricing and one that reinvents it. |
List payments (yekar.xero.list-payments) | Read | Payments applied to invoices, bills and credit notes, with the invoice each one settles. Note the status: a DELETED payment is still returned by this endpoint, so filter on Status=="AUTHORISED" when totalling what was actually received. |
Create payments (yekar.xero.create-payments) | Write | Record payments against invoices, bills or credit notes. This settles real money in the ledger: the invoice's AmountDue drops and it becomes PAID once fully covered. NOT idempotent - Xero has no idempotency key here, so calling twice records the payment twice and over-pays the invoice. Sent with summarizeErrors=false, so the result reports the outcome PER payment. |
Run report (yekar.xero.run-report) | Read | Run one of Xero's own reports - profit and loss, balance sheet, trial balance, bank summary, executive summary, aged receivables or payables - and get it back as flat rows with their section. These are the numbers Xero itself computes, so the organisation's own periods, layouts and account groupings are already applied; totalling query rows would not reproduce them. |
Notes
- Sign in with Xero and tick the organisation this connection should work with - every invoice, contact and payment it writes is stamped with your Xero user, and your role there is the ceiling.
- If you grant more than one organisation, run List tenants and put the right id in Organisation ID on this connection. With several granted and none configured, every call refuses rather than guessing which books to write to.
- A list of invoices is a SUMMARY: Xero omits line items from lists, so use Get invoice whenever the lines matter. Missing lines are absent, not empty.
- Writes go out with summarizeErrors=false, so a batch with one bad record still writes the good ones and reports each outcome. Read the counts - a successful HTTP status does not mean every record landed.
- Create payments is not idempotent: Xero has no idempotency key, so running it twice records the payment twice and over-pays the invoice. Gate it, or check the invoice's AmountDue first.
- Email invoice uses the organisation's own Xero template and the contact's stored address - it takes no recipient or body, and the mail cannot be recalled.
- Xero allows 60 API calls per minute and 5,000 per day per organisation. The daily limit does not clear until Xero's own rollover.
- Xero refresh tokens rotate on every use and expire after 60 days of inactivity, so a connection nothing has run for two months needs reconnecting.