Xero Integration Methodology

    A practical methodology for building Xero integrations — OAuth 2.0, webhooks, the Accounting and Payroll APIs, and marketplace-ready add-ons.

    OAuth 2.0
    Accounting API
    Payroll API
    Webhooks

    Authentication & Multi-Tenant OAuth

    Xero uses OAuth 2.0 with short-lived access tokens and 30-day refresh tokens. Most integrations are multi-tenant, meaning one app connects to many Xero organisations and must keep token state isolated per tenant.

    • Register the app in the Xero Developer Centre and request the right scopes per endpoint
    • Store tenantId (organisation ID) with every access token pair
    • Handle token refresh, disconnection, and revoked consent gracefully
    • Use the token refresh event to update tenant connection metadata

    Accounting, Payroll & Files APIs

    Xero's REST API is split into Accounting, Payroll (AU/NZ/UK), Files, Projects, Assets, and Bank Feeds. Each endpoint has its own validation rules, rate limits, and regional nuances.

    • Use PUT/POST with idempotency keys for invoice and payment creation
    • Batch writes where possible; paginate large lists with the if-modified-since header
    • Map payroll journals carefully between Xero Payroll and general ledger
    • Validate attachments and file types before uploading to the Files API

    Webhooks & Event-Driven Sync

    Xero webhooks push event notifications for contacts, invoices, credit notes, payments, and bank transactions. Reliable webhook handling is the key to near-real-time syncs.

    • Verify webhook signatures using the app signature to reject forged payloads
    • Acknowledge webhooks with 200 OK quickly and queue the work asynchronously
    • Use webhook events to trigger incremental syncs and cache invalidation
    • Implement a reconciliation job to catch any missed events

    Bank Feeds & Marketplace Certification

    Bank feed integrations and Xero App Partner certification require stricter security, UX, and operational standards than internal integrations.

    • Follow Xero's bank feed schema for statement line enrichment
    • Implement OAuth consent screens, data-use disclosure, and logout flows
    • Provide test credentials and sandbox test results for certification
    • Monitor API usage and error rates through Xero's developer dashboard

    Need help implementing this?

    Talk to our integration team about your project.