Xero Accounting API

--- name: "Xero Accounting API" description: "Integrate with Xero: OAuth 2.0 + PKCE, multi-tenant, invoices, payments, bank transactions, webhooks, tax handling (GST/VAT), SDKs, and app certification. Use when building accounting integrations out" version: "1.0.0" author: "skynet" category: "dev" tags: ["xero", "accounting", "api", "oauth", "invoicing", "saas"] --- I will search for any existing Xero-related code or documentation in the repository to provide context-specific examples if available. This technical reference provides a comprehensive guide for integrating with the Xero Accounting API, covering authentication, core resources, common workflows, and operational best practices. --- ### 1. Authentication: OAuth 2.0 with PKCE Xero uses OAuth 2.0. For server-side or desktop apps, **Proof Key for Code Exchange (PKCE)** is recommended to enhance security by preventing authorization code injection. * **Scopes:** Common scopes include `openid`, `profile`, `email`, `accounting.transactions`, `accounting.contacts`, `accounting.settings`, `offline_access` (required for refresh tokens). * **The Tenant ID:** Unlike some APIs where the token is enough, Xero requires a `Xero-tenant-id` header in every request. An authorized user may have access to multiple organizations; you must fetch the connections to allow the user to select the active tenant. * **Endpoint:** `GET https://api.xero.com/connections` * **Token Refresh:** Access tokens expire in 30 minutes. Use the `refresh_token` to get a new `access_token` and a *new* `refresh_token`. ```javascript // Example: Token Refresh (Node.js) const response = await axios.post('https://identity.xero.com/connect/token', { grant_type: 'refresh_token', refresh_token: savedRefreshToken, client_id: process.env.XERO_CLIENT_ID, client_secret: process.env.XERO_CLIENT_SECRET }); ``` --- ### 2. Key Endpoints All Accounting API calls are base-pathed to `https://api.xero.com/api.xro/2.0/`. | Endpoint | Purpose | | :--- | :--- | | `/Contacts` | Create/Update customers and suppliers. | | `/Invoices` | Sales invoices and purchase bills. | | `/Payments` | Apply payments to Invoices or Credit Notes. | | `/BankTransactions` | Spend/Receive money transactions not linked to an invoice. | | `/Accounts` | Chart of Accounts (required for coding transactions). | | `/Items` | Inventory items or services for line items. | | `/ManualJournals` | Low-level accounting adjustments. | | `/Reports` | Access Profit & Loss, Balance Sheet, etc. | --- ### 3. Common Integration Patterns #### Invoice Creation Invoices require a `ContactID`, `Type` (`ACCREC` for sales, `ACCPAY` for bills), and at least one `LineItem`. * **Status:** Use `DRAFT`, `SUBMITTED`, or `AUTHORISED`. * **Deep Links:** Use the `InvoiceID` to generate a link directly to the Xero UI: `https://go.xero.com/AccountsReceivable/View.aspx?InvoiceID={ID}`. #### Payment Reconciliation To pay an invoice, POST to `/Payments`: ```json { "Invoice": { "InvoiceID": "..." }, "Account": { "AccountID": "..." }, "Date": "2023-10-27", "Amount": 150.00 } ``` #### Tax Handling (GST/VAT/Sales Tax) * **TaxTypes:** Xero uses specific strings like `OUTPUT`, `INPUT`, `NONE`, or region-specific codes like `GSTONIMPORTS`. * **Line Amount Types:** Specify if line amounts are `Inclusive`, `Exclusive`, or `NoTax`. This significantly affects rounding calculations. --- ### 4. Webhooks Xero webhooks notify you of changes in real-time. 1. **Intent to Receive:** When you first add a webhook URL, Xero sends a POST with a `x-xero-signature` header. You must respond with the same signature to verify ownership. 2. **Verification:** Every payload is signed with your Webhook Key using **HMACSHA256**. 3. **Events:** Supported for `Invoices`, `Contacts`, `Accounts`, and `BankTransactions`. Events are batched (up to 60 seconds of delay). --- ### 5. SDKs vs. Direct REST * **Official SDKs:** `xero-node`, `xero-python`, `xero-ruby`, `xero-php`, `xero-dotnet`. * **Direct Usage:** Highly recommended for simple integrations to avoid bloated dependencies. Use standard JSON headers, but remember Xero also supports XML (legacy). --- ### 6. Rate Limits Xero enforces strict tiered limits: * **Minute Limit:** 60 calls per minute per tenant. * **Daily Limit:** 5,000 calls per 24-hour period per tenant. * **Concurrent Limit:** 5 calls at any one time. * **App Limit:** 10,000 calls per minute across all tenants for your app. *Strategy: Implement a retry-after logic by inspecting the `X-Rate-Limit-Retry-After` header.* --- ### 7. Gotchas & Differences * **Xero vs. QuickBooks:** Xero is strictly "double-entry" first. You cannot delete a payment; you must void or un-apply it. Contacts are shared between customers and suppliers. * **Rounding:** Xero rounds at the line item level, then sums. If your external system rounds the total first, you may have a 1-2 cent discrepancy. * **Pagination:** Use the `page` parameter (e.g., `?page=1`). Each page returns 100 records. * **If-Modified-Since:** Use this header to sync only changed records. Xero returns a `304 Not Modified` if nothing has changed since the provided UTC timestamp. --- ### 8. Testing: The Demo Company Every Xero user has access to a **Demo Company**. * It contains pre-populated data (Invoices, Bank Statements, Contacts). * It can be reset at any time to a clean state. * **Crucial:** Use the Demo Company for testing Webhooks and Bank Feeds to avoid messing up live production accounts. --- ### 9. Xero App Store & Certification To list your app on the Xero App Store, you must: 1. **Certification:** Pass a technical and UX review. 2. **OAuth Requirements:** Use the standard OAuth 2.0 flow. 3. **Sign-up:** Provide a "Sign up with Xero" button for new users. 4. **Support:** Maintain a support URL and documentation for Xero users. *Note: Certified apps can request higher rate limits if they hit the 5,000 daily cap consistently.*