Xero

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.

Getting Started

Concepts

Interfaces

What it models

Scenarios

Not modelled

​What it models

​Scenarios

​Not modelled

What it models

Scenarios

Not modelled