> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twinbay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Xero

> Contacts, invoices and payments in a Xero organisation, tax and all

The Xero Accounting API a bookkeeping integration actually posts to, over OAuth 2.0 with a tenant. The conformance suite runs `xero-python` — Xero's own client, generated from their OpenAPI document — against the container, so what the twin answers has to survive the SDK's own deserialisation of Xero's `/Date(...)/` encoding and its decimal amounts.

**Slug:** `xero`

## What it models

| Area               | Modelled                                                                                                                                                                                                                                                                                                         |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication     | A bearer access token shaped like Xero's JWT, plus the `xero-tenant-id` naming the organisation it was granted: a missing or withdrawn token is `401` and a tenant the token cannot reach is `403`, both in Xero's problem envelope. `GET /connections` reports the tenant, which is how an integration finds it |
| Rate limits        | The remaining per-minute, per-day and per-app-minute counts on every authorized Accounting API answer — an auth failure and `GET /connections` carry none, because neither spends a tenant's allowance — and a real `429` with `Retry-After` and `X-Rate-Limit-Problem` when one is gone                         |
| Organisation       | One organisation — an NZ demo company with GST at 15% — read through `GET /Organisation`                                                                                                                                                                                                                         |
| Contacts           | Create, read, update through `POST`, list with `where`, `order`, `page` and `pageSize`, archiving rather than deletion, and the unique-name rule Xero enforces                                                                                                                                                   |
| Accounts and items | A chart of accounts with `200 Sales`, `090 Business Bank Account` and `400 Advertising`; creating accounts and items, and the item price and account an invoice line takes from an `ItemCode`                                                                                                                    |
| Invoices           | Create as `DRAFT`, `SubTotal`, `TotalTax`, `Total` and `AmountDue` computed from the line items and their tax types, a sequential `InvoiceNumber`, the `DRAFT` → `SUBMITTED` → `AUTHORISED` → `PAID` lifecycle with `VOIDED` and `DELETED`, and filtering by status, contact or what is still owed               |
| Payments           | Pay an authorised invoice in part or in full, `AmountPaid` and `AmountDue` moving with it, `PAID` once nothing is owed, and refusals for a draft invoice, an overpayment or a non-bank account                                                                                                                   |
| Across the API     | Accounting API collections wrapped and plural in both directions — `GET /connections` is the identity service and answers a bare JSON array — `PUT` that creates against `POST` that updates, `If-Modified-Since` polling, `summarizeErrors=false` partial success, and `Idempotency-Key` replay                 |

Advancing the sandbox approves a submitted invoice. Being overdue is not a status: it is derived from the due date, which the `age_invoice` directive can push into the past.

## Scenarios

`overdue-receivables`, `rate-limited`, `disconnected-tenant`.

## Not modelled

The OAuth authorization code flow itself — the twin is handed a live token — along with webhooks, bank transactions and reconciliation, bank transfers, credit notes, prepayments and overpayments, purchase orders, quotes, manual journals, tracking categories, contact groups, attachments, branding themes, Payroll, Files, Projects and reports. Everything unmodelled answers `501` in Xero's own validation envelope, naming what was asked for. A `where` clause or an `order` this twin cannot apply is refused the same way rather than quietly ignored.