Skip to main content

Xero

Xero is cloud-based accounting software designed for small and medium-sized businesses. It provides comprehensive financial management capabilities including invoicing, bank reconciliation, inventory tracking, purchase orders, expense claims, and real-time financial reporting. Xero helps businesses manage their finances efficiently with features like automated bank feeds, multi-currency support, and integrated payroll.

Authentication Types​

Xero supports 1 authentication method:

  • OAuth - Connect your Xero organization(s) through OAuth 2.0 authentication.
    • Pros: Secure, per-user tracking, supports multiple organizations, granular permission control with scopes
    • Cons: Requires creating a Xero app in the developer portal
    • Best for: All production use cases, organizations requiring secure access with proper authorization

Multi-Tenant Support​

Xero is a multi-tenant platform, meaning a single user can have access to multiple organizations (tenants). After completing the OAuth flow, you'll need to:

  1. Call the Get Connections tool to retrieve the list of authorized organizations
  2. Each organization has a unique Tenant ID
  3. Most API calls require this Tenant ID to specify which organization you're working with

The Tenant ID is automatically managed by the connector after authentication.

Setting up OAuth​

To use Xero with Webrix, you need to create a Xero app and configure OAuth authentication.

1. Create a Xero App​

  1. Go to Xero Developer Portal

  2. Log in with your Xero account

  3. Click New app

  4. Fill in the app details:

    • App name: Give it a descriptive name (e.g., "Webrix Integration")
    • Company or application URL: Your company website
    • OAuth 2.0 redirect URIs: Copy the Redirect URI from Webrix and paste it here
    tip

    You can find the Redirect URI in Webrix when configuring the Xero connector under the OAuth settings. Make sure to copy it exactly as shown.

  5. Click Create app

  6. After creation, you'll see your app details page

  7. Copy the Client ID - you'll need this for Webrix

  8. Click Generate a secret to create a Client Secret, then copy it

    warning

    The client secret is only shown once. If you lose it, you'll need to generate a new one.

2. Configure Scopes​

  1. In your Xero app settings, go to the OAuth 2.0 tab

  2. Under Scopes, ensure the following are enabled based on your needs:

    • openid, profile, email - Basic user identity (required)
    • offline_access - Refresh token support (required)
    • accounting.transactions - Create/update invoices and transactions
    • accounting.transactions.read - View invoices and transactions
    • accounting.contacts - Create/update contacts
    • accounting.contacts.read - View contacts
    • accounting.reports.read - View financial reports
    • accounting.settings - Manage organization settings
    • accounting.settings.read - View organization settings

  3. Click Save

3. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select Xero and click Use

  3. Under Authentication Type, select OAuth

  4. Paste your Client ID from Xero

  5. Paste your Client Secret from Xero

  6. Click Save Changes

4. Test the Connection​

  1. After saving, click Connect to test the OAuth flow

  2. You'll be redirected to Xero's authorization page

  3. Select the organization(s) you want to connect

  4. Click Allow access

  5. You'll be redirected back to Webrix with a successful connection

  6. Use the Get Connections tool to verify which organizations are now accessible

Understanding Access Tokens​

  • Access Token Expiry: Xero access tokens expire after 30 minutes
  • Refresh Tokens: Valid for 60 days if unused
  • Automatic Refresh: The connector automatically refreshes tokens before they expire
  • Reauthorization: If refresh token expires, users must reconnect through OAuth

Rate Limits​

Xero enforces API rate limits to ensure platform stability:

  • Non-certified apps: 5,000 API calls per day per organization
  • Certified apps: Higher limits available (requires certification process)
  • Per-minute limits: 60 calls per minute per organization
tip

If you expect high API usage, consider applying for Xero app certification through the developer portal.

Troubleshooting​

Redirect URI Mismatch Error​

If you see "redirect_uri_mismatch" error during OAuth authorization.

Cause: The redirect URL configured in your Xero app doesn't match the one being used during the OAuth flow.

Solution:

  1. Copy the exact Redirect URI from Webrix
  2. Go to your Xero app → OAuth 2.0 tab → Redirect URIs
  3. Ensure the URI is added exactly as shown (including https:// and any trailing slashes)
  4. Remove any extra or incorrect URIs
  5. Save the changes and try connecting again

Invalid or Missing Tenant ID​

API calls fail with "The Xero-Tenant-Id header is required" or "Invalid tenant ID" errors.

Cause: The connector needs to know which organization to access, but the tenant ID is missing or incorrect.

Solution:

  1. After OAuth, immediately call the Get Connections tool
  2. This returns all authorized organizations with their tenant IDs
  3. The connector automatically uses the tenant ID for subsequent calls
  4. If accessing multiple organizations, ensure you're using the correct tenant ID for each

Token Refresh Failures​

Users are repeatedly prompted to reconnect or get "invalid token" errors.

Cause: The refresh token may have expired (60 days of inactivity) or been revoked.

Solution:

  1. Disconnect and reconnect the Xero integration in Webrix
  2. Verify that the Xero app hasn't been deleted or had its credentials changed
  3. Check that your Xero app's OAuth settings haven't been modified
  4. Ensure users are actively using the integration (at least once every 60 days)

Insufficient Permissions / Scope Errors​

API calls fail with "The user does not have permission" or scope-related errors.

Cause: The requested operation requires scopes that weren't granted during OAuth, or the Xero user lacks permissions.

Solution:

  1. Check that your Xero app has the required scopes enabled in the developer portal
  2. Verify the user has appropriate permissions in Xero (e.g., Standard or Advisor role)
  3. Reconnect the integration to request the new scopes
  4. For write operations, ensure the user has edit permissions in Xero

Rate Limit Exceeded​

API requests fail with 429 (Too Many Requests) errors or "Rate limit exceeded" messages.

Cause: Your application has exceeded Xero's API rate limits (5,000 calls/day for non-certified apps, 60 calls/minute).

Solution:

  1. Implement retry logic with exponential backoff in your workflows
  2. Cache frequently accessed data (e.g., contacts, accounts, tax rates)
  3. Use batch operations where possible
  4. Monitor your API usage through the Xero developer portal
  5. Consider applying for app certification for higher limits

Organization Not Found​

API calls fail with "Organization not found" or similar errors.

Cause: The organization may have been disconnected, the tenant ID is incorrect, or the user no longer has access.

Solution:

  1. Call Get Connections to verify which organizations are currently accessible
  2. Check if the organization still exists and is active in Xero
  3. Verify the user still has access to the organization
  4. Reconnect the integration if needed

Invoice Status Errors​

Cannot update or void invoices with errors about invoice status.

Cause: Xero has strict rules about which operations are allowed based on invoice status:

  • DRAFT invoices can be fully edited or deleted
  • AUTHORISED invoices have limited edit capabilities
  • PAID/VOIDED invoices cannot be modified

Solution:

  1. Check the invoice status first using Get Invoice
  2. For DRAFT invoices: use Update Invoice or delete
  3. For AUTHORISED invoices: use Void Invoice if needed to cancel
  4. For PAID invoices: create a credit note instead of trying to modify
  5. Understand the invoice lifecycle before attempting modifications

Multi-Organization Issues​

Having trouble working with multiple Xero organizations.

Cause: Not properly handling tenant IDs or switching between organizations.

Solution:

  1. Always call Get Connections first to see all available organizations
  2. Store the tenant ID for each organization you want to work with
  3. The connector handles tenant ID automatically for each request
  4. If working with multiple orgs, track which org you're currently accessing
  5. Some users may only have access to one organization

Common Use Cases​

Getting Started​

  1. After OAuth authentication, call Get Connections to see your organizations
  2. Call Get Organization to retrieve organization details
  3. Use List Contacts to see your customers and suppliers
  4. Use List Accounts to see your chart of accounts

Creating an Invoice​

  1. Get the contact ID using List Contacts or Create Contact
  2. Get account codes using List Accounts
  3. Call Create Invoice with contact, line items, and amounts
  4. Optionally call Create Payment to record payment

Reconciling Bank Transactions​

  1. Use List Bank Transactions to see unreconciled transactions
  2. Match transactions with invoices or create new transactions
  3. Use Create Bank Transaction for manual entries
  4. Use Create Payment to link payments to invoices

Financial Reporting​

  1. Use Get Profit & Loss Report for income statement
  2. Use Get Balance Sheet Report for financial position
  3. Use Get Trial Balance Report for account balances
  4. Use Get Bank Summary Report for cash flow analysis