xero-local

A lightweight local emulator for the Xero Accounting API, designed for development and testing without hitting the real Xero service.

Can be used standalone (Python or Docker) or as a LocalStack extension that starts automatically alongside LocalStack.

Supported endpoints

All data is stored in memory and reset on restart. A POST /_xero/reset endpoint is available to clear state between tests.

Quickstart

Python

pip install localstack-xero
xero-local          # starts on http://localhost:5001

Docker

docker run --rm -p 5001:5001 localstack/xero-local

Point your Xero client at http://localhost:5001 instead of https://api.xero.com.

LocalStack extension

localstack extensions install xero
localstack start

The emulator starts automatically with LocalStack and is reachable at http://xero.localhost.localstack.cloud:4566.

Set XERO_PORT (default 5001) or XERO_HOST to change the bind address.

Development

make install-dev   # install with test/lint deps
make test          # run the test suite (42 tests)
make run           # start the emulator locally
make lint          # ruff check
make format        # ruff format + autofix

Docker

make docker-build  # build image for host platform
make docker-run    # run on port 5001
make docker-buildx # build and push multi-arch (amd64 + arm64)

Configuration

CI

Pushes to main and semver tags (v*.*.*) trigger a GitHub Actions workflow that runs the test suite (Python 3.9 and 3.11) and builds and pushes a multi-arch image (linux/amd64, linux/arm64) to Docker Hub. Required secrets: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN.