xero

# Xero Accounting Skill Interact with Xero accounting software via CLI. Manage invoices, contacts, payments, bank transactions, and more. All commands output JSON for easy parsing. ## Script Directory **Agent:** Determine this SKILL.md file's directory as `SKILL_DIR`, then run commands with: ```bash npx -y bun ${SKILL_DIR}/scripts/cli.ts <command> ``` ## Setup ### 1. Get Xero Credentials Users need a Xero Developer account with API credentials: 1. Go to [developer.xero.com/app/manage](https://developer.xero.com/app/manage) 2. Create a **Web App** 3. Set redirect URI: `http://localhost:5001/callback` 4. Copy the **Client ID** and **Client Secret** Note: If you see a scopes configuration page, add: `openid`, `offline_access`, `accounting.contacts`, `accounting.settings`, `accounting.invoices`, `accounting.payments`, `accounting.banktransactions`, `accounting.attachments`. If no scopes page is shown, that's fine - scopes are requested during OAuth. > **Agent note:** If credentials are missing, ask the user for their Client ID and Secret. ### 2. Configure OpenClaw Add credentials to `openclaw.json`: ```json { "skills": { "xero": { "env": { "XERO_CLIENT_ID": "your_client_id", "XERO_CLIENT_SECRET": "your_client_secret" } } } } ``` ### 3. Authenticate ```bash npx -y bun ${SKILL_DIR}/scripts/cli.ts auth login ``` This opens a browser for OAuth. Once complete, verify with: ```bash npx -y bun ${SKILL_DIR}/scripts/cli.ts auth status ``` ## Quick Reference **Command prefix:** `npx -y bun ${SKILL_DIR}/scripts/cli.ts` ### Authentication | Command | Description | |---------|-------------| | `auth login` | Start OAuth flow (opens browser) | | `auth status` | Check authentication status | | `auth logout` | Clear stored credentials | ### Organizations | Command | Description | |---------|-------------| | `tenants list` | List connected Xero organizations | | `tenants select <id>` | Switch active organization | ### Invoices | Command | Description | |---------|-------------| | `invoices list` | List all invoices | | `invoices list --status AUTHORISED` | Filter by status | | `invoices list --contact <id>` | Filter by contact | | `invoices get <id>` | Get invoice details | | `invoices create --contact <id> --items '<json>'` | Create invoice | | `invoices update <id> --status AUTHORISED` | Update status | **Statuses:** `DRAFT`, `AUTHORISED`, `PAID`, `VOIDED` **Types:** `ACCREC` (sales), `ACCPAY` (bills) ### Contacts | Command | Description | |---------|-------------| | `contacts list` | List all contacts | | `contacts list --search "name"` | Search by name | | `contacts list --customers` | Only customers | | `contacts list --suppliers` | Only suppliers | | `contacts get <id>` | Get contact details | | `contacts create --name "X" --email "Y"` | Create contact | ### Accounts | Command | Description | |---------|-------------| | `accounts list` | List all accounts | | `accounts list --type REVENUE` | Filter by type | | `accounts list --class EXPENSE` | Filter by class | | `accounts get <id>` | Get account details | **Types:** `BANK`, `REVENUE`, `EXPENSE`, `FIXED`, `CURRENT`, `LIABILITY`, `EQUITY`, etc. **Classes:** `ASSET`, `EQUITY`, `EXPENSE`, `LIABILITY`, `REVENUE` ### Bank Transactions | Command | Description | |---------|-------------| | `banktransactions list` | List all transactions | | `banktransactions list --type SPEND` | Filter by type | | `banktransactions get <id>` | Get details | | `banktransactions create ...` | Create transaction | | `banktransactions attach <id> <file>` | Attach file | **Types:** `SPEND`, `RECEIVE`, `RECEIVE-OVERPAYMENT`, `SPEND-OVERPAYMENT` ### Payments | Command | Description | |---------|-------------| | `payments list` | List all payments | | `payments list --invoice <id>` | Filter by invoice | | `payments get <id>` | Get payment details | | `payments create ...` | Create payment | | `payments delete <id>` | Void payment | ### Allocations | Command | Description | |---------|-------------| | `allocations list-overpayments` | List overpayments | | `allocations list-prepayments` | List prepayments | | `allocations list-creditnotes` | List credit notes | | `allocations overpayment -o <id> -i <inv> -a <amt>` | Apply overpayment | | `allocations prepayment -p <id> -i <inv> -a <amt>` | Apply prepayment | | `allocations creditnote -c <id> -i <inv> -a <amt>` | Apply credit note | ## Examples ### Create an Invoice ```bash # 1. Find the contact npx -y bun ${SKILL_DIR}/scripts/cli.ts contacts list --search "Acme" # 2. Get revenue account codes npx -y bun ${SKILL_DIR}/scripts/cli.ts accounts list --type REVENUE # 3. Create the invoice npx -y bun ${SKILL_DIR}/scripts/cli.ts invoices create \ --contact "<contact-id>" \ --items '[{"description":"Consulting","quantity":10,"unitAmount":150,"accountCode":"200"}]' \ --reference "INV-001" # 4. Authorize when ready npx -y bun ${SKILL_DIR}/scripts/cli.ts invoices update <invoice-id> --status AUTHORISED ``` ### Record a Payment ```bash # 1. Get bank account ID npx -y bun ${SKILL_DIR}/scripts/cli.ts accounts list --type BANK # 2. Create payment (marks invoice as paid) npx -y bun ${SKILL_DIR}/scripts/cli.ts payments create \ --invoice "<invoice-id>" \ --account "<bank-account-id>" \ --amount 500.00 \ --reconciled ``` ### Create a Contact ```bash npx -y bun ${SKILL_DIR}/scripts/cli.ts contacts create \ --name "Acme Corporation" \ --email "billing@acme.com" \ --customer ``` ### Record Bank Transaction with Receipt ```bash # 1. Create transaction npx -y bun ${SKILL_DIR}/scripts/cli.ts banktransactions create \ --type RECEIVE \ --bank-account "<bank-id>" \ --contact "<contact-id>" \ --items '[{"description":"Payment","unitAmount":500,"accountCode":"200"}]' # 2. Attach receipt npx -y bun ${SKILL_DIR}/scripts/cli.ts banktransactions attach "<transaction-id>" ./receipt.pdf ``` ## Error Handling Errors return JSON: ```json {"error": "Not authenticated. Run auth login"} ``` **Common errors:** | Error | Solution | |-------|----------| | Not authenticated | Run `auth login` | | Token expired | Run `auth login` again | | No organization selected | Run `tenants list` then `tenants select <id>` | ## Security Notes **Token Storage:** OAuth tokens are saved to `data/tokens.json` in the working directory. This file contains sensitive access/refresh tokens - treat it as you would other credentials. **Environment Variables:** The skill reads `XERO_CLIENT_ID` and `XERO_CLIENT_SECRET` from environment (set via OpenClaw config). Optional: `XERO_REDIRECT_URI` (default: `http://localhost:5001/callback`) and `XERO_SCOPES`. **Source Code:** All skill code is bundled in the `scripts/` directory for inspection. Review before granting access to production Xero organizations.