Xero

Stateful Xero emulation of the Accounting API under /api.xro/2.0, with Xero’s JSON envelope, /Date(...)/ dates, and ValidationException errors. It covers the organisation, the chart of accounts and tax rates, contacts and contact groups, items with tracked inventory, invoices and bills with Xero’s status transitions and computed totals, credit notes and allocations, payments, bank transactions, and attachments. Organisations are tenants: every call names one in xero-tenant-id, checked against the token’s connections. OAuth 2.0 runs through an authorize page that picks a user and the organisations to connect, with PKCE, rotating refresh tokens, custom connections (client credentials), and OpenID Connect. Webhooks pass intent to receive before any event is sent, and every delivery is signed with x-xero-signature. The tests drive it with the official xero-node SDK (20.0.0).

At a glance


Package	`@deploybaseline/xero`
Port	`4000` when started alone; named services take consecutive ports
Config key	`xero`
HTTP operations	87, browsable at `http://localhost:3999/docs/xero` while it runs (API reference)
Vendor spec	XeroAPI/Xero-OpenAPI at `5a115f3`

npx @deploybaseline/cli start --service xero

import { createEmulator } from "@deploybaseline/cli";

const xero = await createEmulator({ service: "xero" });
// xero.url is http://localhost:4000

{
  "xero": {
    "organisations": [
      {
        "name": "Demo Company (NZ)",
        "tenant_id": "4a8d6f2e-3b1c-4e5a-9d7f-1c2b3a4d5e6f",
        "contacts": [
          {
            "Name": "Ridgeway University",
            "EmailAddress": "[email protected]"
          }
        ],
        "invoices": [
          {
            "Type": "ACCREC",
            "Contact": {
              "Name": "Ridgeway University"
            },
            "Status": "AUTHORISED",
            "Date": "2026-01-15",
            "DueDate": "2026-02-15",
            "LineItems": [
              {
                "Description": "Consulting",
                "Quantity": 2,
                "UnitAmount": 150,
                "AccountCode": "200"
              }
            ]
          }
        ]
      }
    ],
    "apps": [
      {
        "client_id": "C0FFEE00BA5E11E0000000000000A001",
        "client_secret": "baseline_xero_client_secret_0000000000000000000",
        "name": "Local app",
        "redirect_uris": ["http://localhost:3000/callback"]
      }
    ],
    "access_tokens": [
      {
        "token": "xero-baseline-local-token"
      }
    ]
  }
}

Start

npx @deploybaseline/cli start --service xero

Xero starts only when named in config or with --service. When it is the only enabled service, it listens on http://localhost:4000. A fresh emulator has the organisation Demo Company (NZ) (tenant 4a8d6f2e-3b1c-4e5a-9d7f-1c2b3a4d5e6f), the user [email protected] (who can reach every organisation), and the app C0FFEE00BA5E11E0000000000000A001 / baseline_xero_client_secret_0000000000000000000 with redirect URIs http://localhost:3000/callback and http://localhost:5000/callback. xero-node takes the accounting base URL through accountingApi.basePath. It hard codes the identity and connections hosts, so a test that uses initialize(), updateTenants(), refreshWithRefreshToken(), or getClientCredentialsToken() has to send https://identity.xero.com and https://api.xero.com to the emulator (for example with an axios request interceptor and a wrapped Issuer.discover from xero-node’s own openid-client). Calls made with a token you already hold need only basePath:

import { XeroClient } from "xero-node";

const xero = new XeroClient({ clientId: "", clientSecret: "", redirectUris: [], scopes: [] });
xero.accountingApi.basePath = `${process.env.XERO_EMULATOR_URL ?? "http://localhost:4000"}/api.xro/2.0`;
xero.setTokenSet({ access_token: "xero-baseline-local-token", token_type: "Bearer" });

const tenantId = "4a8d6f2e-3b1c-4e5a-9d7f-1c2b3a4d5e6f";
const { body } = await xero.accountingApi.getInvoices(tenantId);

URL mapping

Real Xero URL	Emulator URL
`https://api.xero.com/api.xro/2.0/...`	`$XERO_EMULATOR_URL/api.xro/2.0/...`
`https://api.xero.com/connections`	`$XERO_EMULATOR_URL/connections`
`https://login.xero.com/identity/connect/authorize`	`$XERO_EMULATOR_URL/identity/connect/authorize`
`https://identity.xero.com/connect/token`	`$XERO_EMULATOR_URL/connect/token`
`https://identity.xero.com/.well-known/openid-configuration`	`$XERO_EMULATOR_URL/.well-known/openid-configuration` (also under `/identity`)

Auth

Every API call needs Authorization: Bearer {access_token}. Access tokens come from the OAuth flow, from access_tokens[] in seed config (fixed tokens that never expire), from POST /_xero/tokens, or from the CLI (tokens the CLI accepts reach every organisation with every scope).

No token: 401 {"Type":null,"Title":"Unauthorized","Status":401,"Detail":"AuthenticationUnsuccessful","Instance":"<xero-correlation-id>","Extensions":{}} with WWW-Authenticate: Bearer. An unknown, revoked, or expired token answers the same with Bearer error=invalid_token.
xero-tenant-id missing, malformed, or not connected to the token: 403 with Title: "Forbidden". Custom connection tokens may leave the header out.
A token without the endpoint’s scope: 401 Detail: "AuthorizationUnsuccessful" with WWW-Authenticate: insufficient_scope. Broad scopes (accounting.transactions, accounting.contacts, accounting.settings, accounting.attachments) and the granular ones (accounting.invoices, accounting.payments, accounting.banktransactions) both work; .read scopes allow GET only.

Connections

GET /connections — List connections: the token’s connections (id, authEventId, tenantId, tenantType: "ORGANISATION", tenantName, createdDateUtc, updatedDateUtc), filtered with ?authEventId=
DELETE /connections/{id} — Delete connection: disconnects one (204, or 404)

Rate limits

Every response carries xero-correlation-id, and X-DayLimit-Remaining, X-MinLimit-Remaining, and X-AppMinLimit-Remaining against Xero’s limits (60 a minute and 5,000 a day per tenant, 10,000 a minute per app). With rate_limits.enforce: true a call past a limit answers 429 with an empty body, Retry-After, and X-Rate-Limit-Problem (minute, day, or appminute).

OAuth 2.0 and OpenID Connect

GET /identity/connect/authorize — Authorize: response_type=code, client_id, redirect_uri (must be registered), scope, state, and optional nonce and code_challenge with code_challenge_method=S256 (required for apps without a secret). The page asks which user signs in and, for accounting scopes, which of the user’s organisations to connect; each becomes a connection. The callback gets code, scope, state, and session_state, or error (invalid_scope, access_denied, unsupported_response_type)
POST /connect/token — Get token: client credentials in Basic auth or the body, and the grants authorization_code (codes are single use and live 5 minutes), refresh_token (rotates; the old token keeps working for oauth.refresh_grace_seconds, 30 minutes by default; refresh tokens live 60 days), and client_credentials for apps with a custom_connection. Access tokens are RS256 JWTs that live 30 minutes, with Xero’s claims (client_id, sub, xero_userid, authentication_event_id, global_session_id, scope). With openid, an ID token (5 minutes) carries email, given_name, family_name, and nonce. A refresh token needs offline_access. Errors are 400 {"error":"invalid_client"}, invalid_grant, unsupported_grant_type, unauthorized_client, or invalid_scope
POST /connect/revocation — Revoke token: with a refresh token, it revokes it and removes the user’s connections to the app
POST /connect/introspect — Introspect token
GET /connect/userinfo — Get user info
GET /connect/endsession — End session
GET /.well-known/openid-configuration — OpenID configuration: keys at /.well-known/openid-configuration/jwks; both also under /identity

Accounting API

All accounting routes are under /api.xro/2.0.

Organisation

GET /Organisation — Get organisation

Accounts

GET /Accounts — List accounts
GET /Accounts/{id} — Get account
PUT /Accounts — Create account: one account
POST /Accounts/{id} — Update account
DELETE /Accounts/{id} — Delete account: unused, non-system accounts

New organisations get the standard chart (090 and 091 bank accounts, 200 Sales, 400 to 493 expenses, 610 Accounts Receivable, 630 Inventory, 800 Accounts Payable, 820 tax, 960 Retained Earnings, and more).

Tax rates

GET /TaxRates — List tax rates: the region’s rates (NZ 15% GST, AU 10% GST, UK 20% VAT; the US set is a Baseline simplification)
GET /TaxRates/{TaxType} — Get tax rate

Contacts

POST /Contacts — Create or update contacts: the same path takes GET to list and PUT to create
GET /Contacts/{id or ContactNumber} — Get contact
POST /Contacts/{id} — Update contact

Archive with ContactStatus: "ARCHIVED" (lists leave archived contacts out unless includeArchived=true). Names are unique among active contacts.

Contact groups

PUT /ContactGroups — Create contact group: GET on the same path lists them
POST /ContactGroups/{id} — Update contact group: rename, or Status: "DELETED"; GET on the same path reads one
PUT /ContactGroups/{id}/Contacts — Add contacts to group
DELETE /ContactGroups/{id}/Contacts — Remove all contacts from group
DELETE /ContactGroups/{id}/Contacts/{ContactID} — Remove contact from group

Items

POST /Items — Create or update items: the same path takes GET to list and PUT to create
POST /Items/{id or Code} — Update item: GET on the same path reads one
DELETE /Items/{id} — Delete item: 204

Tracked items need an INVENTORY asset account and PurchaseDetails.COGSAccountCode; QuantityOnHand and TotalCostPool follow authorised bills and invoices. Selling more than is on hand fails with Insufficient stock. Items are eligible for backorder. unless allowBackorders=true.

Invoices

POST /Invoices — Create or update invoices: the same path takes GET to list and PUT to create
POST /Invoices/{id or InvoiceNumber} — Update invoice: GET on the same path reads one

ACCREC and ACCPAY; LineAmountTypes Exclusive, Inclusive, or NoTax; totals, tax, and AmountDue computed; automatic INV-0001 numbers; transitions DRAFT to SUBMITTED, AUTHORISED, or DELETED, SUBMITTED back to DRAFT, AUTHORISED to VOIDED; paid invoices accept only the fields Xero allows. Line items are updated, added, and removed by LineItemID. A contact named only by Name is created.

Credit notes

POST /CreditNotes — Create or update credit notes: the same path takes GET to list and PUT to create
POST /CreditNotes/{id} — Update credit note: GET on the same path reads one
PUT /CreditNotes/{id}/Allocations — Allocate credit note
DELETE /CreditNotes/{id}/Allocations/{AllocationID} — Delete allocation

Payments

POST /Payments — Create payments: the same path takes GET to list and PUT to create
GET /Payments/{id} — Get payment
POST /Payments/{id} — Reverse payment: with {"Status":"DELETED"}

Payments go to AUTHORISED documents from a bank account (or one with EnablePaymentsToAccount), may be partial, and may not exceed the amount due; a fully paid invoice turns PAID.

Bank transactions

POST /BankTransactions — Create or update bank transactions: the same path takes GET to list and PUT to create
POST /BankTransactions/{id} — Update bank transaction: GET on the same path reads one

SPEND and RECEIVE, Status: "DELETED" to remove.

Attachments

Attachments work on invoices, credit notes, bank transactions, contacts, and accounts:

GET /{Type}/{id}/Attachments — List attachments
GET /{Type}/{id}/Attachments/{AttachmentID or FileName} — Get attachment: the file
POST /{Type}/{id}/Attachments/{FileName} — Upload attachment: PUT or POST with the raw file as the body (IncludeOnline=true on invoices and credit notes)

Up to 10 a document and 25 MB each; uploading a name again replaces it.

Lists and filters

where takes Xero’s Dynamic LINQ syntax: ==, !=, <, >, <=, >=, AND, OR, NOT, &&, ||, parentheses, nested fields (Contact.Name), .Contains(), .StartsWith(), .EndsWith(), .ToLower(), .ToUpper(), guid("..."), and DateTime(2026, 1, 31). String comparisons ignore case. A bad expression answers 400 QueryParseException with Dynamic LINQ’s message (No property or field 'X' exists in type 'Invoice')
order takes a comma list of fields with ASC or DESC
If-Modified-Since returns records changed after the time
IDs, Statuses, InvoiceNumbers, ContactIDs, createdByMyApp, includeArchived, and searchTerm (contacts and invoices)
page and pageSize (100 by default, up to 1,000) on invoices, contacts, credit notes, bank transactions, and payments, with a pagination object (page, pageSize, pageCount, itemCount). Invoice and credit note line items come with paging, single reads, and Statuses filters. summaryOnly=true gives the lightest form
unitdp=4 keeps four decimal places on unit amounts

Writes

PUT creates and POST creates or updates (matching by ID, or by ContactNumber, InvoiceNumber, or item Code). Bodies may be {"Invoices":[...]}, a bare list, or one object. With the default summarizeErrors=true one bad element rolls back the whole batch and the answer is 400 ValidationException (ErrorNumber: 10) with each failed element and its ValidationErrors. With summarizeErrors=false the good elements are saved and the answer is 200 with StatusAttributeString OK or ERROR on each. Malformed JSON answers 400 PostDataInvalidException, and an unknown ID answers 404 with the plain text The resource you're looking for cannot be found. Idempotency-Key on a PUT or POST replays the first answer for six minutes. The same key with a different request answers 400 Idempotency Key: KEY is used with a different request., and a key over 128 characters answers Idempotency Key: KEY with length N is too long.

Webhooks

Give an app a webhook: { url, key } in seed config, or POST /_xero/apps/{client_id}/webhook with {"url","key"}. Before the first event the emulator runs intent to receive: one correctly signed and one incorrectly signed empty batch ({"events":[],"firstEventSequence":0,"lastEventSequence":0,"entropy":"..."}). The receiver must answer 200 to the first and 401 to the second; a receiver that does not gets no events until intent to receive passes again (POST /_xero/apps/{client_id}/webhook/intent runs it now and returns the result). Each delivery is signed with x-xero-signature, the base64 HMAC-SHA256 of the raw body keyed with the webhook key. Changes one API request makes reach each subscribed, connected app as one batch:

{
  "events": [
    {
      "resourceUrl": "http://localhost:4000/api.xro/2.0/Invoices/7f1c...",
      "resourceId": "7f1c...",
      "eventDateUtc": "2026-10-20T10:15:03.120",
      "eventType": "CREATE",
      "eventCategory": "INVOICE",
      "tenantId": "4a8d6f2e-3b1c-4e5a-9d7f-1c2b3a4d5e6f",
      "tenantType": "ORGANISATION"
    }
  ],
  "firstEventSequence": 1,
  "lastEventSequence": 1,
  "entropy": "QWERTYUIOPASDFGHJKLZ"
}

Invoices and contacts send CREATE and UPDATE (a payment or allocation updates its invoice). A failed delivery is retried right away and then after 1, 4, and 16 seconds (Xero retries every 15 minutes for a day).

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: string, signature: string, key: string): boolean {
  const expected = createHmac("sha256", key).update(rawBody).digest("base64");
  return signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Controls

POST /_xero/apps/{client_id}/webhook — Set app webhook: status PENDING
POST /_xero/apps/{client_id}/webhook/intent — Run intent to receive
POST /_xero/tokens — Mint token: optional client_id, user (email), organisations (names or tenant IDs), and scopes mints tokens and connections without the browser

Seed config

{
  "xero": {
    "organisations": [
      {
        "name": "Demo Company (NZ)",
        "tenant_id": "4a8d6f2e-3b1c-4e5a-9d7f-1c2b3a4d5e6f",
        "country_code": "NZ",
        "contacts": [
          {
            "Name": "Ridgeway University",
            "EmailAddress": "[email protected]"
          }
        ],
        "items": [
          {
            "Code": "WIDGET",
            "Name": "Widget",
            "SalesDetails": {
              "UnitPrice": 20,
              "AccountCode": "200"
            }
          }
        ],
        "invoices": [
          {
            "Type": "ACCREC",
            "Contact": {
              "Name": "Ridgeway University"
            },
            "Status": "AUTHORISED",
            "Date": "2026-01-15",
            "DueDate": "2026-02-15",
            "LineItems": [
              {
                "Description": "Consulting",
                "Quantity": 2,
                "UnitAmount": 150,
                "AccountCode": "200"
              }
            ]
          }
        ]
      }
    ],
    "users": [
      {
        "email": "[email protected]",
        "first_name": "Alice",
        "last_name": "Accountant",
        "organisations": ["Demo Company (NZ)"]
      }
    ],
    "apps": [
      {
        "client_id": "C0FFEE00BA5E11E0000000000000A001",
        "client_secret": "baseline_xero_client_secret_0000000000000000000",
        "name": "Local app",
        "redirect_uris": ["http://localhost:3000/callback"],
        "webhook": {
          "url": "http://localhost:3000/xero/webhooks",
          "key": "baseline-xero-webhook-key"
        }
      },
      {
        "client_id": "PKCE0000000000000000000000000001",
        "public": true,
        "redirect_uris": ["http://localhost:3000/callback"]
      },
      {
        "client_id": "CUSTOM00000000000000000000000001",
        "client_secret": "custom-connection-secret",
        "custom_connection": {
          "organisation": "Demo Company (NZ)",
          "scopes": ["accounting.transactions", "accounting.contacts"]
        }
      }
    ],
    "access_tokens": [
      {
        "token": "xero-baseline-local-token"
      }
    ],
    "rate_limits": {
      "enforce": false,
      "per_minute": 60,
      "per_day": 5000,
      "app_per_minute": 10000
    },
    "oauth": {
      "refresh_grace_seconds": 1800
    }
  }
}

country_code: NZ, AU, UK, or US: currency, tax rates, timezone

Records are Xero JSON saved through the same validation as the API, in the order accounts, contacts, items, invoices, credit notes, payments, bank transactions. Seeding is idempotent. signing_key: { private_jwk } keeps token signatures stable across fresh starts.

Inspector

GET /_inspector shows organisations and users, contacts, invoices and credit notes, payments and bank transactions, apps and connections, and webhook deliveries.

Limits

Payroll, Assets, Projects, Files, Bank Feeds, and Finance APIs; quotes, purchase orders, receipts, expense claims, manual journals, overpayments and prepayments, batch payments, repeating invoices, reports, history and notes, tracking categories, branding themes, currencies other than the base currency, online invoice links, and PDFs.

Conformance


Routes	87 supported or partial, 0 planned
Route gate	fail
Spec gate	fail, 1 allowed (XeroAPI/Xero-OpenAPI at `5a115f3`)
SDKs tested	`[email protected]`, `[email protected]`, `[email protected]`
Dual mode	not yet

See CONFORMANCE.md for every provider.

Overview

Identity and auth

Workspace and productivity

Messaging and email

Payments and commerce

Developer platforms

CRM and support

Finance and ERP

At a glance

Start

URL mapping

Auth

Connections

Rate limits

OAuth 2.0 and OpenID Connect

Accounting API

Organisation

Accounts

Tax rates

Contacts

Contact groups

Items

Invoices

Credit notes

Payments

Bank transactions

Attachments

Lists and filters

Writes

Webhooks

Controls

Seed config

Inspector

Limits

Conformance

​At a glance

​Start

​URL mapping

​Auth

​Connections

​Rate limits

​OAuth 2.0 and OpenID Connect

​Accounting API

​Organisation

​Accounts

​Tax rates

​Contacts

​Contact groups

​Items

​Invoices

​Credit notes

​Payments

​Bank transactions

​Attachments

​Lists and filters

​Writes

​Webhooks

​Controls

​Seed config

​Inspector

​Limits

​Conformance

At a glance

Start

URL mapping

Auth

Connections

Rate limits

OAuth 2.0 and OpenID Connect

Accounting API

Organisation

Accounts

Tax rates

Contacts

Contact groups

Items

Invoices

Credit notes

Payments

Bank transactions

Attachments

Lists and filters

Writes

Webhooks

Controls

Seed config

Inspector

Limits

Conformance