How to Integrate Retool with Xero

Go to developer.xero.com and sign in with your Xero credentials. Navigate to 'My Apps' and click 'New app'. Choose the app type — for a Retool integration that accesses your own Xero organisation, select 'Web app' to use the Authorization Code OAuth flow. Fill in the application name (e.g., 'Retool Finance Dashboard'), your company's URL, and the redirect URI. For Retool Cloud, the redirect URI is https://oauth.retool.com/oauth/user/oauthcallback. For self-hosted Retool, use your BASE_DOMAIN value followed by /oauth/user/oauthcallback. You can add multiple redirect URIs if needed. Under OAuth 2.0 scopes, select the permissions your dashboard needs. For a read-only financial dashboard: openid (required), profile (required), email (required), accounting.transactions.read (invoices, bills, bank transactions), accounting.contacts.read (customers, suppliers), and accounting.settings.read (organisation details). If your Retool app needs to create or update records, add the write variants of these scopes. After saving the app, Xero shows your Client ID. Click 'Generate a secret' to create your Client Secret. Copy both values — they will not be shown again. Store them securely; you'll paste them into the Retool Resource configuration in the next step.

In Retool, open the Resources tab from the left sidebar navigation. Click 'Create a resource' and select 'REST API'. Name the resource 'Xero API'. Set the base URL to https://api.xero.com/api.xro/2.0. This is the base URL for Xero's Accounting API v2 — all queries targeting accounting data (invoices, contacts, transactions) will use paths relative to this URL. For authentication, select 'OAuth 2.0'. Enter the Client ID and Client Secret from your Xero developer application. Set the Authorization URL to https://login.xero.com/identity/connect/authorize and the Token URL to https://identity.xero.com/connect/token. In the Scope field, enter the scopes you configured: openid profile email accounting.transactions.read accounting.contacts.read accounting.settings.read (space-separated). Next, add a custom header that all Xero queries require. Under 'Headers', click 'Add header'. Set the name to Xero-tenant-id. For the value, you have two options: enter your specific tenant ID directly if you're only connecting to one organisation, or use a configuration variable with {{ retoolContext.configVars.XERO_TENANT_ID }} to make it configurable without changing the resource settings. Also add an Accept header with value application/json. Save the resource and click 'Connect' to complete the OAuth flow. Retool will open a Xero authentication popup — sign in and grant access to your organisation. After authorizing, the resource status should show as connected.

The Xero-tenant-id is essential — every API call to Xero's Accounting API requires it to identify which organisation you're querying. To find your tenant ID, create a temporary resource or query pointing to Xero's connections endpoint. Create a new query in a Retool app. Select your Xero API resource. Set the method to GET and the path to /Connections. Note: this endpoint uses the Xero base URL https://api.xero.com (not the Accounting API URL), so you may need to override the base URL in the query or create a separate 'Xero Identity' resource with base URL https://api.xero.com. Run the query. The response is an array of connection objects, each containing tenantId (the value you need), tenantType (ORGANISATION or PRACTICE), tenantName (your Xero organisation name), and createdDateUtc. Copy the tenantId value for the organisation you want to connect to. For accounting firms managing multiple clients, store all tenant IDs in a configuration variable or Retool Database table with associated client names. Build a Select dropdown in your Retool apps that lets users choose a client organisation — then pass the corresponding tenant ID in the Xero-tenant-id header of each query using {{ organisationSelect.value }}.

1// Response from GET https://api.xero.com/connections
2// Example response structure:
3[
4  {
5    "id": "abc123de-f456-7890-abcd-ef1234567890",
6    "authEventId": "abc123de-f456-7890-abcd-ef1234567890",
7    "tenantId": "12345678-abcd-1234-abcd-123456789012",
8    "tenantType": "ORGANISATION",
9    "tenantName": "Acme Ltd",
10    "createdDateUtc": "/Date(1609459200000)/",
11    "updatedDateUtc": "/Date(1609459200000)/"
12  }
13]

With the resource configured and tenant ID in place, create the core data queries for your financial dashboard. In a new Retool app, create a query named 'getInvoices'. Select the Xero API resource, set method to GET, and path to /Invoices. Add URL parameters: Type (set to ACCREC for accounts receivable invoices, or leave blank for all), Statuses (set to AUTHORISED,SUBMITTED for unpaid invoices), page (set to {{ pagination.currentPage || 1 }} for pagination), and pageSize (set to 100). Xero's Invoices endpoint returns detailed invoice objects with fields for contact name, amounts, due dates, and line items. Create a second query 'getContacts' targeting /Contacts with parameters like where (Xero's filter syntax, e.g., IsCustomer=true) and summaryOnly=true for faster loading. Create a third query 'getBankSummary' targeting /BankAccounts to pull account balances. For bank transactions, use /BankTransactions with date range parameters. Note that Xero uses its own date format: /Date(1609459200000+0000)/ for JSON responses. Your transformer must parse these. Create a transformer to convert Xero dates and reshape the response for the dashboard.

1// JavaScript transformer for Xero invoice data
2const invoices = data.Invoices || [];
3
4// Helper: parse Xero's /Date(timestamp+offset)/ format
5function parseXeroDate(xeroDate) {
6  if (!xeroDate) return null;
7  const match = xeroDate.match(/\/Date\((\d+)[+-]\d+\)\//);
8  if (!match) return xeroDate;
9  return new Date(parseInt(match[1])).toLocaleDateString('en-GB', {
10    year: 'numeric', month: 'short', day: 'numeric'
11  });
12}
13
14return invoices.map(inv => ({
15  invoiceNumber: inv.InvoiceNumber || 'N/A',
16  contact: inv.Contact?.Name || 'Unknown',
17  status: inv.Status,
18  issueDate: parseXeroDate(inv.Date),
19  dueDate: parseXeroDate(inv.DueDate),
20  total: `${inv.CurrencyCode} ${inv.Total?.toFixed(2) || '0.00'}`,
21  amountDue: `${inv.CurrencyCode} ${inv.AmountDue?.toFixed(2) || '0.00'}`,
22  daysOverdue: inv.DueDate
23    ? Math.max(0, Math.floor((Date.now() - parseInt(inv.DueDate.match(/\d+/)[0])) / 86400000))
24    : 0,
25  invoiceId: inv.InvoiceID
26}));

Build the Retool financial dashboard components. At the top of the canvas, add a Stats Row using three Statistic components showing total accounts receivable (sum of AmountDue for unpaid ACCREC invoices), total overdue amount (invoices where daysOverdue > 0), and number of outstanding invoices. Bind the Statistic component values using JavaScript expressions: {{ getInvoices_transformed.value.reduce((sum, inv) => sum + parseFloat(inv.amountDue.replace(/[^0-9.]/g, '') || 0), 0).toFixed(2) }}. Below the stats, add a Bar Chart component. Set the dataset to a query or transformer that groups invoices by aging bucket. Use the 'Group by' feature in a separate transformer that categorises invoices as 'Current (0-30)', 'Overdue 31-60', 'Overdue 61-90', and 'Overdue 90+'. Add a Table component showing the transformed invoice data. Configure columns: invoiceNumber, contact, status (as a Tag), issueDate, dueDate, amountDue, and a 'View in Xero' action button that constructs a Xero web URL and opens it in a new tab. Add filter components above the table: a Select for invoice status (AUTHORISED, SUBMITTED, PAID), a TextInput for contact name search, and a Date Range picker for due date filtering. Connect these to the query parameters in your getInvoices query. For complex multi-resource dashboards combining Xero with your CRM or payment system, RapidDev's team can help design the data joining logic and query architecture.

1// Transformer to group invoices into aging buckets for the bar chart
2const invoices = getInvoices_transformed.value || [];
3
4const buckets = {
5  'Current (0-30 days)': 0,
6  'Overdue 31-60 days': 0,
7  'Overdue 61-90 days': 0,
8  'Overdue 90+ days': 0
9};
10
11invoices.forEach(inv => {
12  const days = inv.daysOverdue || 0;
13  const amount = parseFloat(inv.amountDue.replace(/[^0-9.]/g, '') || 0);
14  if (days <= 30) buckets['Current (0-30 days)'] += amount;
15  else if (days <= 60) buckets['Overdue 31-60 days'] += amount;
16  else if (days <= 90) buckets['Overdue 61-90 days'] += amount;
17  else buckets['Overdue 90+ days'] += amount;
18});
19
20return Object.entries(buckets).map(([label, value]) => ({
21  bucket: label,
22  amount: parseFloat(value.toFixed(2))
23}));