# Xero Small business accounting. Manage contacts, raise invoices and bills, record payments and bank transactions, and pull reports. | Property | Value | | --- | --- | | Slug | `xero` | | Definition version | `0.1.0` | | Base URL | `https://api.xero.com/api.xro/2.0` | | Auth schemes | `oauth2` | | Action tools | 38 | | By class | 19 read, 12 write, 7 destructive | | Triggers | 0 | | Provider rate limit | 60 requests per 1m, per account | ## Measured routing accuracy 61 golden cases replayed through the router over the whole index: measured over corpus `ea4f12ad2948` (65 toolkits, 2283 tools indexed and 13 declared uncallable), 38 cases written by hand and 23 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all. | Measure | Cases | Share | | --- | --- | --- | | top-1 | 41/61 | 67.2% | | top-8 | 56/61 | 91.8% | The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. `just eval-live` measures the same cases through the live reranker. ## Authentication Connect an entity with `ConnectionsService.InitiateConnection`, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only. ### `oauth2` | Property | Value | | --- | --- | | Authorization URL | `https://login.xero.com/identity/connect/authorize` | | Token URL | `https://identity.xero.com/connect/token` | | Default scopes | `offline_access`, `accounting.contacts`, `accounting.transactions`, `accounting.settings`, `accounting.reports.read` | | Refresh tokens | yes, the refresh daemon renews ahead of expiry | ## Tools 38 action tools. The catalog-wide slug is `xero.`, which is what `search_tools` returns and `call_tool` takes. ### `xero.create_contact` Create a new customer or supplier contact in Xero. Use when the user wants to add, register, or set up someone to invoice or bill before raising a transaction against them. Requires a name; email and tax number are optional. Class `write` (writes, no confirmation needed). Scopes `accounting.contacts`. Calls `PUT /Contacts`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `account_number` | string | no | Your own internal reference code for this contact. | | `email_address` | string | no | Contact's email address. | | `first_name` | string | no | Contact's first name, for an individual. | | `is_customer` | boolean | no | True if this contact is invoiced (a sales customer). | | `is_supplier` | boolean | no | True if this contact is billed (a purchases supplier). | | `last_name` | string | no | Contact's last name, for an individual. | | `name` | string | **yes** | Contact or business name, e.g. "Acme Builders Ltd". | | `tax_number` | string | no | Tax or business registration number, e.g. an ABN or VAT id. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Contacts` | array of object | | | `Contacts[].ContactID` | string | | | `Contacts[].ContactStatus` | string | | | `Contacts[].EmailAddress` | string | | | `Contacts[].IsCustomer` | boolean | | | `Contacts[].IsSupplier` | boolean | | | `Contacts[].Name` | string | | Also retrieved by: "set up a new customer in xero", "add a supplier we buy from", "register someone before I invoice them", "get this vendor into the books", "onboard a new client's billing details". ### `xero.get_contact` Get one Xero contact by id: name, email, tax number, and whether they are a customer, supplier, or both. Use when the user names a specific contact. For finding a contact by name or browsing all of them, use list_contacts. Class `read` (reads only). Scopes `accounting.contacts.read`. Calls `GET /Contacts/{{params.contact_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `contact_id` | string | **yes** | Xero ContactID (GUID). | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Contacts` | array of object | | | `Contacts[].AccountNumber` | string | | | `Contacts[].ContactID` | string | | | `Contacts[].ContactStatus` | string | | | `Contacts[].EmailAddress` | string | | | `Contacts[].IsCustomer` | boolean | | | `Contacts[].IsSupplier` | boolean | | | `Contacts[].Name` | string | | | `Contacts[].TaxNumber` | string | | | `Contacts[].UpdatedDateUTC` | string | | Also retrieved by: "pull up this client's details", "what's on file for this supplier", "check their tax number", "look up someone's billing info". ### `xero.list_contacts` List or search Xero contacts, optionally filtered by a raw where clause. Use when the user asks who our customers or suppliers are, wants to look someone up by name, or browses the contact list. For one known contact, use get_contact. Class `read` (reads only). Scopes `accounting.contacts.read`. Calls `GET /Contacts`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `order` | string | no | Field to sort by, e.g. "Name" or "Name DESC". | | `page` | integer | no | Page number, 100 contacts per page. Defaults to 1. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | | `where` | string | no | Xero API filter expression, e.g. 'Name.Contains("Acme")' or 'IsSupplier==true'. Omit to return every contact. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Contacts` | array of object | | | `Contacts[].ContactID` | string | | | `Contacts[].ContactStatus` | string | | | `Contacts[].EmailAddress` | string | | | `Contacts[].IsCustomer` | boolean | | | `Contacts[].IsSupplier` | boolean | | | `Contacts[].Name` | string | | Also retrieved by: "who do we buy from", "find the client with this name", "show everyone we bill", "search our books for a vendor". ### `xero.update_contact` Edit an existing Xero contact's name, email, tax number, or account number. Use when the user wants to update, correct, or change a customer's or supplier's details. Only the fields given change; omit others to leave them as is. Class `write` (writes, no confirmation needed). Scopes `accounting.contacts`. Calls `POST /Contacts/{{params.contact_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `account_number` | string | no | New internal reference code for this contact. | | `contact_id` | string | **yes** | Xero ContactID to update. | | `email_address` | string | no | New email address. | | `name` | string | no | New contact or business name. | | `tax_number` | string | no | New tax or business registration number. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Contacts` | array of object | | | `Contacts[].ContactID` | string | | | `Contacts[].ContactStatus` | string | | | `Contacts[].EmailAddress` | string | | | `Contacts[].Name` | string | | Also retrieved by: "fix their email on file", "this supplier's tax number changed", "correct the billing details we have", "change what's saved for them". ### `xero.archive_contact` Archive a Xero contact, taking them off the active customer or supplier list without deleting their invoice or payment history. Reversible only by editing the contact's status back in Xero directly. Use when the user wants to remove, retire, or clean up a contact that is no longer active. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `accounting.contacts`. Calls `POST /Contacts/{{params.contact_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `contact_id` | string | **yes** | Xero ContactID to archive. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Contacts` | array of object | | | `Contacts[].ContactID` | string | | | `Contacts[].ContactStatus` | string | | Also retrieved by: "get this old client off the active list", "retire a supplier we don't use anymore", "clean up someone we no longer deal with", "hide a vendor we stopped working with". ### `xero.create_invoice` Create a new sales invoice in Xero, billing a contact for one or more line items. Use when the user wants to invoice, bill, or charge a customer. Leave status as DRAFT to review first, or set AUTHORISED to make it payable right away. For a bill you owe, use create_bill instead. Class `write` (writes, no confirmation needed). Scopes `accounting.transactions`. Calls `PUT /Invoices`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `contact_id` | string | **yes** | Xero ContactID of the customer being invoiced. | | `date` | string | no | Invoice date, YYYY-MM-DD. Defaults to today. | | `due_date` | string | no | Payment due date, YYYY-MM-DD. | | `line_items` | array of object | **yes** | Invoice line items, e.g. [{"Description": "Consulting hours", "Quantity": 10, "UnitAmount": 150, "AccountCode": "200", "TaxType": "OUTPUT"}]. | | `reference` | string | no | Free-text reference shown on the invoice, e.g. a PO number. | | `status` | string, one of DRAFT, SUBMITTED, AUTHORISED | no | Invoice status. Defaults to DRAFT. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Invoices` | array of object | | | `Invoices[].AmountDue` | number | | | `Invoices[].Contact` | object | | | `Invoices[].Contact.ContactID` | string | | | `Invoices[].Contact.Name` | string | | | `Invoices[].CurrencyCode` | string | | | `Invoices[].InvoiceID` | string | | | `Invoices[].InvoiceNumber` | string | | | `Invoices[].Status` | string | | | `Invoices[].Total` | number | | | `Invoices[].Type` | string | | Also retrieved by: "bill this client for the work", "send someone a bill for hours worked", "charge a customer for the order", "start a bill I can send out", "raise a sales bill for consulting". ### `xero.get_invoice` Get one Xero sales invoice by id: its status, amount due, amount paid, due date, and line items. Use when the user names a specific invoice. For a bill you owe, use get_bill. Class `read` (reads only). Scopes `accounting.transactions.read`. Calls `GET /Invoices/{{params.invoice_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `invoice_id` | string | **yes** | Xero InvoiceID (GUID). | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Invoices` | array of object | | | `Invoices[].AmountDue` | number | | | `Invoices[].AmountPaid` | number | | | `Invoices[].Contact` | object | | | `Invoices[].Contact.ContactID` | string | | | `Invoices[].Contact.Name` | string | | | `Invoices[].CurrencyCode` | string | | | `Invoices[].Date` | string | | | `Invoices[].DueDate` | string | | | `Invoices[].InvoiceID` | string | | | `Invoices[].InvoiceNumber` | string | | | `Invoices[].LineItems` | array of object | | | `Invoices[].LineItems[].Description` | string | | | `Invoices[].LineItems[].LineAmount` | number | | | `Invoices[].LineItems[].Quantity` | number | | | `Invoices[].LineItems[].UnitAmount` | number | | | `Invoices[].Status` | string | | | `Invoices[].SubTotal` | number | | | `Invoices[].Total` | number | | | `Invoices[].TotalTax` | number | | | `Invoices[].Type` | string | | Also retrieved by: "pull up this specific bill I sent", "check what's still owed on this one", "how much has this client paid so far". ### `xero.list_invoices` List Xero sales invoices, optionally filtered by contact, status, or a raw where clause. Use when the user asks about unpaid invoices, a customer's billing history, or outstanding accounts receivable. For bills owed to suppliers, use list_bills. Class `read` (reads only). Scopes `accounting.transactions.read`. Calls `GET /Invoices`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `contact_id` | string | no | Only invoices for this contact id. | | `order` | string | no | Field to sort by, e.g. "DueDate" or "Total DESC". | | `page` | integer | no | Page number, 100 invoices per page. Defaults to 1. | | `status` | string, one of DRAFT, SUBMITTED, AUTHORISED, PAID, VOIDED, DELETED | no | Only invoices in this state. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | | `where` | string | no | Additional Xero API filter expression, e.g. 'AmountDue > 0'. Combined with contact_id and status when given. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Invoices` | array of object | | | `Invoices[].AmountDue` | number | | | `Invoices[].Contact` | object | | | `Invoices[].Contact.ContactID` | string | | | `Invoices[].Contact.Name` | string | | | `Invoices[].DueDate` | string | | | `Invoices[].InvoiceID` | string | | | `Invoices[].InvoiceNumber` | string | | | `Invoices[].Status` | string | | | `Invoices[].Total` | number | | Also retrieved by: "show what customers still owe us", "what's outstanding on our sales", "pull unpaid bills we've sent out", "what hasn't this client paid off yet". ### `xero.update_invoice` Edit an existing Xero sales invoice's line items, due date, reference, or status while it is still a draft or submitted. Use when the user wants to correct, add to, or authorise an invoice that has not been paid. For a bill you owe, use update_bill. Class `write` (writes, no confirmation needed). Scopes `accounting.transactions`. Calls `POST /Invoices/{{params.invoice_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `due_date` | string | no | New payment due date, YYYY-MM-DD. | | `invoice_id` | string | **yes** | Xero InvoiceID to update. | | `line_items` | array of object | no | Replacement line items, in the same shape as create_invoice. | | `reference` | string | no | New free-text reference. | | `status` | string, one of DRAFT, SUBMITTED, AUTHORISED | no | New invoice status, e.g. AUTHORISED to make it payable. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Invoices` | array of object | | | `Invoices[].AmountDue` | number | | | `Invoices[].InvoiceID` | string | | | `Invoices[].Status` | string | | | `Invoices[].Total` | number | | Also retrieved by: "add a line to a bill I haven't sent yet", "fix the due date on this one", "lock this in so it's ready to be paid". ### `xero.email_invoice` Email an authorised Xero sales invoice to its contact using their invoice email template. Use when the user wants to send, deliver, or mail an invoice to whoever owes it. The invoice must already be authorised. Class `write` (writes, no confirmation needed). Scopes `accounting.transactions`. Calls `POST /Invoices/{{params.invoice_id}}/Email`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `invoice_id` | string | **yes** | Xero authorised InvoiceID to email. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Invoices` | array of object | | | `Invoices[].InvoiceID` | string | | | `Invoices[].Status` | string | | Also retrieved by: "get this bill out to the client", "deliver it so they can pay", "mail them what they owe", "get it out the door to whoever owes it". ### `xero.void_invoice` Void an authorised Xero sales invoice that will never be paid. Irreversible; the invoice stays on record marked voided instead of being deleted, and any allocated payments are removed. Use when the user wants to cancel, kill, or invalidate an invoice sent by mistake. For a bill, use void_bill. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `accounting.transactions`. Calls `POST /Invoices/{{params.invoice_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `invoice_id` | string | **yes** | Xero InvoiceID to void. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Invoices` | array of object | | | `Invoices[].InvoiceID` | string | | | `Invoices[].Status` | string | | Also retrieved by: "kill this one, it went out by mistake", "cancel a bill that should never be paid", "this shouldn't have been sent at all". ### `xero.create_bill` Create a new bill owed to a supplier in Xero, from one or more line items. Use when the user wants to record, enter, or log an expense or purchase bill from a supplier. For an invoice you are sending a customer, use create_invoice instead. Class `write` (writes, no confirmation needed). Scopes `accounting.transactions`. Calls `PUT /Invoices`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `contact_id` | string | **yes** | Xero ContactID of the supplier being billed. | | `date` | string | no | Bill date, YYYY-MM-DD. Defaults to today. | | `due_date` | string | no | Payment due date, YYYY-MM-DD. | | `line_items` | array of object | **yes** | Bill line items, e.g. [{"Description": "Office supplies", "Quantity": 1, "UnitAmount": 220, "AccountCode": "429", "TaxType": "INPUT"}]. | | `reference` | string | no | Free-text reference, e.g. the supplier's bill number. | | `status` | string, one of DRAFT, SUBMITTED, AUTHORISED | no | Bill status. Defaults to DRAFT. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Invoices` | array of object | | | `Invoices[].AmountDue` | number | | | `Invoices[].Contact` | object | | | `Invoices[].Contact.ContactID` | string | | | `Invoices[].Contact.Name` | string | | | `Invoices[].InvoiceID` | string | | | `Invoices[].InvoiceNumber` | string | | | `Invoices[].Status` | string | | | `Invoices[].Total` | number | | | `Invoices[].Type` | string | | Also retrieved by: "log an expense from a supplier", "enter what we owe for office supplies", "record a purchase we need to pay later". ### `xero.get_bill` Get one Xero bill by id: its status, amount due, amount paid, due date, and line items. Use when the user names a specific bill owed to a supplier. For a sales invoice, use get_invoice. Class `read` (reads only). Scopes `accounting.transactions.read`. Calls `GET /Invoices/{{params.bill_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `bill_id` | string | **yes** | Xero InvoiceID (GUID) of the bill. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Invoices` | array of object | | | `Invoices[].AmountDue` | number | | | `Invoices[].AmountPaid` | number | | | `Invoices[].Contact` | object | | | `Invoices[].Contact.ContactID` | string | | | `Invoices[].Contact.Name` | string | | | `Invoices[].DueDate` | string | | | `Invoices[].InvoiceID` | string | | | `Invoices[].InvoiceNumber` | string | | | `Invoices[].LineItems` | array of object | | | `Invoices[].LineItems[].Description` | string | | | `Invoices[].LineItems[].LineAmount` | number | | | `Invoices[].LineItems[].Quantity` | number | | | `Invoices[].LineItems[].UnitAmount` | number | | | `Invoices[].Status` | string | | | `Invoices[].Total` | number | | Also retrieved by: "what do we still owe on this one", "pull up details on this supplier expense", "check the due date on what we owe them". ### `xero.list_bills` List bills owed to suppliers in Xero, optionally filtered by contact, status, or a raw where clause. Use when the user asks what we owe, which supplier bills are unpaid, or wants accounts payable. For invoices sent to customers, use list_invoices. Class `read` (reads only). Scopes `accounting.transactions.read`. Calls `GET /Invoices`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `contact_id` | string | no | Only bills from this supplier contact id. | | `order` | string | no | Field to sort by, e.g. "DueDate" or "Total DESC". | | `page` | integer | no | Page number, 100 bills per page. Defaults to 1. | | `status` | string, one of DRAFT, SUBMITTED, AUTHORISED, PAID, VOIDED, DELETED | no | Only bills in this state. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | | `where` | string | no | Additional Xero API filter expression, e.g. 'AmountDue > 0'. Combined with contact_id and status when given. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Invoices` | array of object | | | `Invoices[].AmountDue` | number | | | `Invoices[].Contact` | object | | | `Invoices[].Contact.ContactID` | string | | | `Invoices[].Contact.Name` | string | | | `Invoices[].DueDate` | string | | | `Invoices[].InvoiceID` | string | | | `Invoices[].InvoiceNumber` | string | | | `Invoices[].Status` | string | | | `Invoices[].Total` | number | | Also retrieved by: "what do we owe right now", "show unpaid supplier expenses", "pull our accounts payable". ### `xero.update_bill` Edit an existing Xero bill's line items, due date, reference, or status while it is still a draft or submitted. Use when the user wants to correct, add to, or authorise a supplier bill that is not yet paid. For a sales invoice, use update_invoice. Class `write` (writes, no confirmation needed). Scopes `accounting.transactions`. Calls `POST /Invoices/{{params.bill_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `bill_id` | string | **yes** | Xero InvoiceID of the bill to update. | | `due_date` | string | no | New payment due date, YYYY-MM-DD. | | `line_items` | array of object | no | Replacement line items, in the same shape as create_bill. | | `reference` | string | no | New free-text reference. | | `status` | string, one of DRAFT, SUBMITTED, AUTHORISED | no | New bill status, e.g. AUTHORISED to make it payable. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Invoices` | array of object | | | `Invoices[].AmountDue` | number | | | `Invoices[].InvoiceID` | string | | | `Invoices[].Status` | string | | | `Invoices[].Total` | number | | Also retrieved by: "fix the amount on what we owe them", "add a line to an expense we haven't approved", "authorise this so it's ready to be paid". ### `xero.void_bill` Void an authorised Xero bill that will never be paid. Irreversible; the bill stays on record marked voided instead of being deleted, and any allocated payments are removed. Use when the user wants to cancel, kill, or invalidate a supplier bill entered by mistake. For a sales invoice, use void_invoice. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `accounting.transactions`. Calls `POST /Invoices/{{params.bill_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `bill_id` | string | **yes** | Xero InvoiceID of the bill to void. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Invoices` | array of object | | | `Invoices[].InvoiceID` | string | | | `Invoices[].Status` | string | | Also retrieved by: "this expense was entered by mistake", "we never actually owed this, kill it", "cancel something logged wrongly". ### `xero.create_payment` Record a payment against a Xero invoice or bill, in full or in part. Use when the user wants to mark an invoice paid, apply a payment received, or pay off a bill from a bank account. Does not move money itself; it records that a payment already happened. Class `write` (writes, no confirmation needed). Scopes `accounting.transactions`. Calls `PUT /Payments`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `account_id` | string | **yes** | Xero AccountID the payment is made from or into. | | `amount` | number | **yes** | Payment amount in the invoice's currency. | | `date` | string | no | Payment date, YYYY-MM-DD. Defaults to today. | | `invoice_id` | string | **yes** | Xero InvoiceID (invoice or bill) the payment applies to. | | `reference` | string | no | Free-text reference for this payment. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Payments` | array of object | | | `Payments[].Amount` | number | | | `Payments[].Date` | string | | | `Payments[].Invoice` | object | | | `Payments[].Invoice.InvoiceID` | string | | | `Payments[].Invoice.InvoiceNumber` | string | | | `Payments[].PaymentID` | string | | | `Payments[].Status` | string | | Also retrieved by: "mark this as paid", "apply money we received against the bill", "record that the client settled up", "pay off a supplier from the bank". ### `xero.get_payment` Get one Xero payment by id: its amount, date, status, and the invoice or bill it was applied to. Use when the user asks whether a specific payment went through. Class `read` (reads only). Scopes `accounting.transactions.read`. Calls `GET /Payments/{{params.payment_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `payment_id` | string | **yes** | Xero PaymentID (GUID). | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Payments` | array of object | | | `Payments[].Amount` | number | | | `Payments[].Date` | string | | | `Payments[].Invoice` | object | | | `Payments[].Invoice.InvoiceID` | string | | | `Payments[].Invoice.InvoiceNumber` | string | | | `Payments[].PaymentID` | string | | | `Payments[].PaymentType` | string | | | `Payments[].Status` | string | | Also retrieved by: "did this actually clear", "check on money applied to this bill", "confirm we got paid on this one". ### `xero.list_payments` List payments recorded in Xero, optionally filtered by a raw where clause. Use when the user asks for recent payments, what has been collected, or a payment history across invoices and bills. Class `read` (reads only). Scopes `accounting.transactions.read`. Calls `GET /Payments`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `order` | string | no | Field to sort by, e.g. "Date DESC". | | `page` | integer | no | Page number, 100 payments per page. Defaults to 1. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | | `where` | string | no | Xero API filter expression, e.g. 'Invoice.Contact.ContactID==guid("...")'. Omit to return every payment. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Payments` | array of object | | | `Payments[].Amount` | number | | | `Payments[].Date` | string | | | `Payments[].Invoice` | object | | | `Payments[].Invoice.InvoiceID` | string | | | `Payments[].Invoice.InvoiceNumber` | string | | | `Payments[].PaymentID` | string | | | `Payments[].Status` | string | | Also retrieved by: "what have we collected lately", "show money applied against our bills", "pull a history of what's come in and gone out". ### `xero.delete_payment` Reverse a Xero payment, marking it deleted and reopening the amount it was applied to on the original invoice or bill. Irreversible; the payment cannot be restored. Use when the user wants to undo, unapply, or take back a payment entered by mistake. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `accounting.transactions`. Calls `POST /Payments/{{params.payment_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `payment_id` | string | **yes** | Xero PaymentID to reverse. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Payments` | array of object | | | `Payments[].PaymentID` | string | | | `Payments[].Status` | string | | Also retrieved by: "undo that, it was applied wrongly", "take back money we marked as received", "this shouldn't have been marked settled". ### `xero.create_bank_transaction` Record money spent or received directly from a Xero bank account, outside of an invoice or bill. Use when the user wants to log a bank fee, cash purchase, or direct deposit that has no linked invoice. For money against an invoice or bill, use create_payment. Class `write` (writes, no confirmation needed). Scopes `accounting.transactions`. Calls `PUT /BankTransactions`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `account_id` | string | **yes** | Xero AccountID of the bank account the money moved through. | | `contact_id` | string | **yes** | Xero ContactID the transaction is with. | | `date` | string | no | Transaction date, YYYY-MM-DD. Defaults to today. | | `line_items` | array of object | **yes** | Transaction line items, e.g. [{"Description": "Bank fee", "Quantity": 1, "UnitAmount": 12, "AccountCode": "404"}]. | | `reference` | string | no | Free-text reference for this transaction. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | | `type` | string, one of SPEND, RECEIVE | **yes** | SPEND for money paid out, RECEIVE for money paid in. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `BankTransactions` | array of object | | | `BankTransactions[].BankTransactionID` | string | | | `BankTransactions[].Date` | string | | | `BankTransactions[].Status` | string | | | `BankTransactions[].Total` | number | | | `BankTransactions[].Type` | string | | Also retrieved by: "log a bank fee", "record cash we spent with no bill", "enter a direct deposit that hit the account". ### `xero.get_bank_transaction` Get one Xero bank transaction by id: whether it is a spend or receive, its status, amount, and line items. Use when the user names a specific bank transaction not tied to an invoice. Class `read` (reads only). Scopes `accounting.transactions.read`. Calls `GET /BankTransactions/{{params.bank_transaction_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `bank_transaction_id` | string | **yes** | Xero BankTransactionID (GUID). | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `BankTransactions` | array of object | | | `BankTransactions[].BankTransactionID` | string | | | `BankTransactions[].Contact` | object | | | `BankTransactions[].Contact.ContactID` | string | | | `BankTransactions[].Contact.Name` | string | | | `BankTransactions[].Date` | string | | | `BankTransactions[].LineItems` | array of object | | | `BankTransactions[].LineItems[].Description` | string | | | `BankTransactions[].LineItems[].LineAmount` | number | | | `BankTransactions[].LineItems[].UnitAmount` | number | | | `BankTransactions[].Status` | string | | | `BankTransactions[].Total` | number | | | `BankTransactions[].Type` | string | | Also retrieved by: "what was this charge on the bank account", "pull up details on this spend entry", "check this deposit that came through". ### `xero.list_bank_transactions` List Xero bank transactions, optionally filtered by bank account or a raw where clause. Use when the user asks what has moved through a bank account outside of invoices and bills, or wants a spend and receive history. Class `read` (reads only). Scopes `accounting.transactions.read`. Calls `GET /BankTransactions`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `account_id` | string | no | Only transactions through this bank AccountID. | | `order` | string | no | Field to sort by, e.g. "Date DESC". | | `page` | integer | no | Page number, 100 transactions per page. Defaults to 1. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | | `where` | string | no | Additional Xero API filter expression, e.g. 'Type=="SPEND"'. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `BankTransactions` | array of object | | | `BankTransactions[].BankTransactionID` | string | | | `BankTransactions[].Date` | string | | | `BankTransactions[].Status` | string | | | `BankTransactions[].Total` | number | | | `BankTransactions[].Type` | string | | Also retrieved by: "what's moved through the account with no bill", "show direct spending and deposits", "pull a history of bank fees". ### `xero.void_bank_transaction` Void a Xero bank transaction that was entered by mistake. Irreversible; the transaction stays on record marked voided instead of being deleted. Use when the user wants to cancel or undo a spend or receive money entry that never should have been recorded. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `accounting.transactions`. Calls `POST /BankTransactions/{{params.bank_transaction_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `bank_transaction_id` | string | **yes** | Xero BankTransactionID to void. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `BankTransactions` | array of object | | | `BankTransactions[].BankTransactionID` | string | | | `BankTransactions[].Status` | string | | Also retrieved by: "that bank entry was a mistake", "undo something logged against the account wrongly", "this spend never should have happened". ### `xero.create_bank_transfer` Move money between two of the organisation's own Xero bank accounts. Use when the user wants to transfer, move, or shift funds from one bank account to another, not to pay a contact. Class `write` (writes, no confirmation needed). Scopes `accounting.transactions`. Calls `PUT /BankTransfers`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `amount` | number | **yes** | Amount to transfer, in the organisation's base currency. | | `date` | string | no | Transfer date, YYYY-MM-DD. Defaults to today. | | `from_account_id` | string | **yes** | Xero AccountID the funds leave. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | | `to_account_id` | string | **yes** | Xero AccountID the funds land in. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `BankTransfers` | array of object | | | `BankTransfers[].Amount` | number | | | `BankTransfers[].BankTransferID` | string | | | `BankTransfers[].Date` | string | | | `BankTransfers[].FromBankAccount` | object | | | `BankTransfers[].FromBankAccount.AccountID` | string | | | `BankTransfers[].ToBankAccount` | object | | | `BankTransfers[].ToBankAccount.AccountID` | string | | Also retrieved by: "move money between our accounts", "shift funds from checking to savings", "send cash from one account to another internally". ### `xero.get_bank_transfer` Get one Xero bank transfer by id: the amount, date, and the two bank accounts it moved money between. Use when the user asks about a specific transfer between accounts. Class `read` (reads only). Scopes `accounting.transactions.read`. Calls `GET /BankTransfers/{{params.bank_transfer_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `bank_transfer_id` | string | **yes** | Xero BankTransferID (GUID). | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `BankTransfers` | array of object | | | `BankTransfers[].Amount` | number | | | `BankTransfers[].BankTransferID` | string | | | `BankTransfers[].Date` | string | | | `BankTransfers[].FromBankAccount` | object | | | `BankTransfers[].FromBankAccount.AccountID` | string | | | `BankTransfers[].ToBankAccount` | object | | | `BankTransfers[].ToBankAccount.AccountID` | string | | Also retrieved by: "check on a move between our accounts", "what happened with that internal shift of funds", "pull up details on this specific move of money". ### `xero.list_bank_transfers` List transfers of money between the organisation's own Xero bank accounts. Use when the user asks what has moved between accounts, not payments to or from contacts. Class `read` (reads only). Scopes `accounting.transactions.read`. Calls `GET /BankTransfers`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `page` | integer | no | Page number, 100 transfers per page. Defaults to 1. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `BankTransfers` | array of object | | | `BankTransfers[].Amount` | number | | | `BankTransfers[].BankTransferID` | string | | | `BankTransfers[].Date` | string | | Also retrieved by: "show money moved between accounts", "what's shifted internally lately", "pull our history of moves between accounts". ### `xero.delete_bank_transfer` Permanently delete a Xero bank transfer between two of the organisation's own accounts. Irreversible; only works if the transfer has not been reconciled in either bank account. Use when the user wants to undo, reverse, or remove a transfer entered by mistake. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `accounting.transactions`. Calls `DELETE /BankTransfers/{{params.bank_transfer_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `bank_transfer_id` | string | **yes** | Xero BankTransferID to delete. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `BankTransfers` | array of object | | | `BankTransfers[].BankTransferID` | string | | Also retrieved by: "undo that move between accounts", "that internal shift of funds was a mistake", "scrap a move of money we shouldn't have made". ### `xero.create_account` Add a new account to the Xero chart of accounts. Use when the user wants to set up, add, or create a new ledger account, expense category, or income category to code transactions against. Class `write` (writes, no confirmation needed). Scopes `accounting.settings`. Calls `PUT /Accounts`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `code` | string | **yes** | Unique account code, e.g. "620". | | `description` | string | no | Internal note describing what this account is for. | | `name` | string | **yes** | Account name, e.g. "Consulting Income". | | `tax_type` | string | no | Default tax type for this account, e.g. "OUTPUT" or "INPUT". | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | | `type` | string | **yes** | Xero account type, e.g. "REVENUE", "EXPENSE", "CURRENT", "FIXED", "BANK". | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Accounts` | array of object | | | `Accounts[].AccountID` | string | | | `Accounts[].Code` | string | | | `Accounts[].Name` | string | | | `Accounts[].Status` | string | | | `Accounts[].Type` | string | | Also retrieved by: "set up a new expense category", "add a ledger code for this kind of spend", "I need a new income category to code things to". ### `xero.get_account` Get one Xero chart of accounts entry by id: its code, name, type, and status. Use when the user names a specific ledger account. For browsing or searching the whole chart, use list_accounts. Class `read` (reads only). Scopes `accounting.settings.read`. Calls `GET /Accounts/{{params.account_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `account_id` | string | **yes** | Xero AccountID (GUID). | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Accounts` | array of object | | | `Accounts[].AccountID` | string | | | `Accounts[].Code` | string | | | `Accounts[].Description` | string | | | `Accounts[].Name` | string | | | `Accounts[].Status` | string | | | `Accounts[].TaxType` | string | | | `Accounts[].Type` | string | | Also retrieved by: "what's this ledger code for", "pull up details on this expense category", "check what this specific account is set up as". ### `xero.list_accounts` List the accounts in the Xero chart of accounts, optionally filtered by a raw where clause, e.g. only bank, revenue, or expense type accounts. Use when the user asks what accounts, expense categories, or income categories exist to code a transaction against, or which of the organisation's accounts are bank accounts. Class `read` (reads only). Scopes `accounting.settings.read`. Calls `GET /Accounts`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `order` | string | no | Field to sort by, e.g. "Code" or "Name". | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | | `where` | string | no | Xero API filter expression, e.g. 'Type=="BANK"' or 'Status=="ACTIVE"'. Omit to return every account. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Accounts` | array of object | | | `Accounts[].AccountID` | string | | | `Accounts[].Code` | string | | | `Accounts[].Name` | string | | | `Accounts[].Status` | string | | | `Accounts[].Type` | string | | Also retrieved by: "what can I code this to", "show our chart of accounts", "what expense categories do we have", "which of our accounts are bank accounts". ### `xero.update_account` Edit an existing Xero chart of accounts entry's name, tax type, or description. Use when the user wants to rename, recode the tax treatment of, or relabel an account. The account code and type cannot be changed once transactions exist against it. Class `write` (writes, no confirmation needed). Scopes `accounting.settings`. Calls `POST /Accounts/{{params.account_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `account_id` | string | **yes** | Xero AccountID to update. | | `description` | string | no | New internal note describing what this account is for. | | `name` | string | no | New account name. | | `tax_type` | string | no | New default tax type for this account. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Accounts` | array of object | | | `Accounts[].AccountID` | string | | | `Accounts[].Name` | string | | | `Accounts[].TaxType` | string | | Also retrieved by: "rename this expense category", "change the tax treatment on this ledger code", "relabel what a code is used for". ### `xero.archive_account` Archive an account in the Xero chart of accounts, hiding it from the list used to code new transactions while keeping its transaction history. Reversible only by editing the account's status back in Xero directly. Use when the user wants to retire, remove, or stop using an account going forward. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `accounting.settings`. Calls `POST /Accounts/{{params.account_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `account_id` | string | **yes** | Xero AccountID to archive. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Accounts` | array of object | | | `Accounts[].AccountID` | string | | | `Accounts[].Status` | string | | Also retrieved by: "retire this expense category, we don't use it", "stop using this ledger code going forward", "hide a code from the coding list without erasing its history". ### `xero.get_profit_and_loss` Run the Xero Profit and Loss report for a date range: income, expenses, and net profit broken into their account sections. Use when the user asks how the business is performing, or for revenue and expense totals over a period. Class `read` (reads only). Scopes `accounting.reports.read`. Calls `GET /Reports/ProfitAndLoss`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `from_date` | string | no | Report start date, YYYY-MM-DD. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | | `to_date` | string | no | Report end date, YYYY-MM-DD. Defaults to today. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Reports` | array of object | | | `Reports[].ReportDate` | string | | | `Reports[].ReportName` | string | | | `Reports[].Rows` | array of object | | | `Reports[].Rows[].Cells` | array of object | | | `Reports[].Rows[].RowType` | string | | | `Reports[].Rows[].Rows` | array of object | | | `Reports[].Rows[].Title` | string | | Also retrieved by: "how's the business doing this quarter", "show revenue and expenses for last month", "what's our net margin for the period". ### `xero.get_balance_sheet` Run the Xero Balance Sheet report as of a date: assets, liabilities, and equity broken into their account sections. Use when the user asks what the business owns, owes, or is worth as of a point in time. Class `read` (reads only). Scopes `accounting.reports.read`. Calls `GET /Reports/BalanceSheet`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `date` | string | no | As-of date for the report, YYYY-MM-DD. Defaults to today. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Reports` | array of object | | | `Reports[].ReportDate` | string | | | `Reports[].ReportName` | string | | | `Reports[].Rows` | array of object | | | `Reports[].Rows[].Cells` | array of object | | | `Reports[].Rows[].RowType` | string | | | `Reports[].Rows[].Rows` | array of object | | | `Reports[].Rows[].Title` | string | | Also retrieved by: "what's the business worth right now", "show what we own and owe as of today", "give me a snapshot of assets and equity". ### `xero.get_aged_receivables` Run the Xero Aged Receivables report for one contact: their unpaid sales invoices grouped by how overdue each one is. Use when the user asks who owes us money, how overdue a customer's invoices are, or wants a collections view. For what we owe, use get_aged_payables. Class `read` (reads only). Scopes `accounting.reports.read`. Calls `GET /Reports/AgedReceivablesByContact`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `contact_id` | string | **yes** | Xero ContactID of the customer to report on. | | `date` | string | no | As-of date for the aging, YYYY-MM-DD. Defaults to today. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Reports` | array of object | | | `Reports[].ReportDate` | string | | | `Reports[].ReportName` | string | | | `Reports[].Rows` | array of object | | | `Reports[].Rows[].Cells` | array of object | | | `Reports[].Rows[].RowType` | string | | | `Reports[].Rows[].Title` | string | | Also retrieved by: "who's behind on paying us", "how overdue is this client's balance", "show collections for this customer". ### `xero.get_aged_payables` Run the Xero Aged Payables report for one contact: their unpaid bills grouped by how overdue each one is. Use when the user asks what we owe a supplier, how overdue our bills are, or wants a cash flow planning view. For money owed to us, use get_aged_receivables. Class `read` (reads only). Scopes `accounting.reports.read`. Calls `GET /Reports/AgedPayablesByContact`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `contact_id` | string | **yes** | Xero ContactID of the supplier to report on. | | `date` | string | no | As-of date for the aging, YYYY-MM-DD. Defaults to today. | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Reports` | array of object | | | `Reports[].ReportDate` | string | | | `Reports[].ReportName` | string | | | `Reports[].Rows` | array of object | | | `Reports[].Rows[].Cells` | array of object | | | `Reports[].Rows[].RowType` | string | | | `Reports[].Rows[].Title` | string | | Also retrieved by: "how overdue are our bills to this supplier", "what do we owe them and how late is it", "give me a cash flow planning view of what's due out". ### `xero.get_organisation` Get details of the connected Xero organisation: its legal name, base currency, financial year end, and country. Use when the user asks basic questions about the company itself, e.g. its reporting currency or fiscal year end, rather than its transactions. Class `read` (reads only). Scopes `accounting.settings.read`. Calls `GET /Organisation`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `tenant_id` | string | **yes** | Xero connected organisation id (tenant id). | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `Organisations` | array of object | | | `Organisations[].BaseCurrency` | string | | | `Organisations[].CountryCode` | string | | | `Organisations[].FinancialYearEndDay` | integer | | | `Organisations[].FinancialYearEndMonth` | integer | | | `Organisations[].LegalName` | string | | | `Organisations[].Name` | string | | | `Organisations[].OrganisationID` | string | | Also retrieved by: "what's our reporting currency", "when does our fiscal year end", "basic company details on file".