How to Integrate Lovable with Xero

Go to developer.xero.com and sign in with your Xero account. Click 'New app' in the developer dashboard. Give your app a name, select 'Web app' as the integration type, and enter your company URL. In the Redirect URIs field, add your Edge Function callback URL: https://[your-project].supabase.co/functions/v1/xero-oauth. Click 'Create app'. On the app settings page, you'll see your Client ID (a UUID format string). For OAuth2 PKCE apps, Xero does not display a Client Secret — PKCE replaces the client secret with a dynamically generated code verifier/challenge pair. This is one key difference from QuickBooks's OAuth2 implementation. Note: while Xero PKCE apps don't require a client secret for the authorization code exchange, server-side apps (like Edge Functions) can still optionally use a Client Secret for additional security during the token endpoint call. In the app settings, you can generate a Client Secret if you want to use it. For this tutorial, we'll include it as an optional additional security layer. In the 'Scopes' section, select the permissions your app needs. For accounting data, select 'openid', 'profile', 'email', 'accounting.transactions' (invoices, bank transactions, credit notes), 'accounting.contacts' (customers and suppliers), and 'offline_access' (required to get a refresh token for persistent access). Click 'Save'.

Open your Lovable project, click '+' → Cloud → Secrets. Add XERO_CLIENT_ID with your app's Client ID. Add XERO_REDIRECT_URI with the full Edge Function URL (https://[your-project].supabase.co/functions/v1/xero-oauth). Add XERO_SCOPES with value 'openid profile email accounting.transactions accounting.contacts offline_access'. The OAuth2 PKCE flow works as follows: your app generates a random code_verifier (a 43-128 character random string), computes a code_challenge by hashing it with SHA-256 and base64url-encoding the result, includes the code_challenge in the authorization URL, redirects the user to Xero's authorization endpoint, receives the authorization code at your redirect URI, exchanges the code (plus the original code_verifier) for access and refresh tokens at Xero's token endpoint. For a single-user setup (your own Xero account), you can complete this flow once using Xero's OAuth 2.0 Playground at developer.xero.com/documentation/oauth2/pkce-flow or manually. Store the resulting access_token (short-lived, 30 minutes), refresh_token (long-lived), and token_set expiry in Supabase's xero_tokens table. Add XERO_REFRESH_TOKEN to Cloud Secrets with the initial refresh token obtained after authorization. For multi-user apps, create a 'Connect Xero' button that triggers the PKCE flow for each user — the Edge Function generates the code verifier/challenge and redirects to Xero's authorization URL. The callback Edge Function completes the exchange and stores tokens per user.

Build the main Edge Function that handles all Xero API operations. Like QuickBooks, Xero's access tokens expire after 30 minutes — significantly shorter than most services. Every Edge Function invocation must check if the access token is expired and refresh it before making the API call. The token refresh flow for Xero uses the standard OAuth2 refresh grant: POST to https://identity.xero.com/connect/token with grant_type=refresh_token and the stored refresh_token. The response includes a new access_token and a new refresh_token (rotate on each use — always save the latest one). Update both in the database after each refresh. Xero's REST API follows a consistent pattern: all accounting API calls go to https://api.xero.com/api.xro/2.0/{Resource} with the Xero-Tenant-Id header specifying which organization's data to access. Common endpoints: GET /Invoices (with Status filter), POST /Invoices (create), GET /Contacts, POST /Payments (record payment against invoice). Xero supports both XML and JSON. Always use JSON by including the Accept: application/json header. For list endpoints, Xero uses If-Modified-Since header-based pagination — pass the header with a datetime to get only records modified since that time, which is efficient for incremental syncs.

1// supabase/functions/xero/index.ts
2import { serve } from "https://deno.land/std@0.168.0/http/server.ts";
3import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
4
5const XERO_BASE = "https://api.xero.com/api.xro/2.0";
6const TOKEN_URL = "https://identity.xero.com/connect/token";
7const corsHeaders = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "POST, OPTIONS", "Access-Control-Allow-Headers": "Content-Type, Authorization" };
8
9async function refreshTokens(supabase: any, userId: string, refreshToken: string) {
10  const clientId = Deno.env.get("XERO_CLIENT_ID") ?? "";
11  const res = await fetch(TOKEN_URL, {
12    method: "POST",
13    headers: { "Content-Type": "application/x-www-form-urlencoded" },
14    body: new URLSearchParams({
15      grant_type: "refresh_token",
16      refresh_token: refreshToken,
17      client_id: clientId,
18    }),
19  });
20  const data = await res.json();
21  if (!data.access_token) throw new Error("Token refresh failed: " + JSON.stringify(data));
22  const expiresAt = new Date(Date.now() + data.expires_in * 1000).toISOString();
23  await supabase.from("xero_tokens").update({
24    access_token: data.access_token,
25    refresh_token: data.refresh_token,
26    expires_at: expiresAt,
27    updated_at: new Date().toISOString(),
28  }).eq("user_id", userId);
29  return data.access_token;
30}
31
32serve(async (req) => {
33  if (req.method === "OPTIONS") return new Response(null, { headers: corsHeaders });
34  try {
35    const authHeader = req.headers.get("Authorization") ?? "";
36    const supabase = createClient(Deno.env.get("SUPABASE_URL") ?? "", Deno.env.get("SUPABASE_SERVICE_ROLE_KEY") ?? "");
37    const { data: { user } } = await createClient(Deno.env.get("SUPABASE_URL") ?? "", Deno.env.get("SUPABASE_ANON_KEY") ?? "", { global: { headers: { Authorization: authHeader } } }).auth.getUser();
38    const userId = user?.id;
39    if (!userId) return new Response(JSON.stringify({ error: "Unauthorized" }), { status: 401, headers: corsHeaders });
40
41    const { data: tokenRow } = await supabase.from("xero_tokens").select("*").eq("user_id", userId).single();
42    if (!tokenRow) return new Response(JSON.stringify({ error: "No Xero connection found" }), { status: 404, headers: corsHeaders });
43
44    let accessToken = tokenRow.access_token;
45    if (new Date(tokenRow.expires_at) < new Date(Date.now() + 60000)) {
46      accessToken = await refreshTokens(supabase, userId, tokenRow.refresh_token);
47    }
48
49    const headers = {
50      Authorization: `Bearer ${accessToken}`,
51      "Xero-Tenant-Id": tokenRow.tenant_id,
52      Accept: "application/json",
53      "Content-Type": "application/json",
54    };
55    const { action, invoice } = await req.json();
56
57    if (action === "get-invoices") {
58      const res = await fetch(`${XERO_BASE}/Invoices?Statuses=AUTHORISED,SUBMITTED`, { headers });
59      const data = await res.json();
60      return new Response(JSON.stringify({ invoices: data.Invoices ?? [] }), { headers: { ...corsHeaders, "Content-Type": "application/json" } });
61    }
62    if (action === "get-contacts") {
63      const res = await fetch(`${XERO_BASE}/Contacts`, { headers });
64      const data = await res.json();
65      return new Response(JSON.stringify({ contacts: data.Contacts ?? [] }), { headers: { ...corsHeaders, "Content-Type": "application/json" } });
66    }
67    if (action === "create-invoice" && invoice) {
68      const res = await fetch(`${XERO_BASE}/Invoices`, { method: "POST", headers, body: JSON.stringify({ Invoices: [invoice] }) });
69      const data = await res.json();
70      return new Response(JSON.stringify({ invoice: data.Invoices?.[0] }), { headers: { ...corsHeaders, "Content-Type": "application/json" } });
71    }
72    return new Response(JSON.stringify({ error: "Unknown action" }), { status: 400, headers: corsHeaders });
73  } catch (err) {
74    return new Response(JSON.stringify({ error: err.message }), { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } });
75  }
76});

With the Edge Function handling authentication and API proxying, build the invoice management frontend. Ask Lovable to create a dashboard that fetches and displays invoices from Xero, shows their status (DRAFT, SUBMITTED, AUTHORISED, PAID, VOIDED), and provides actions for common operations. Xero invoice data is rich: each invoice includes the Contact name, invoice number, issue date, due date, subtotal, total tax, total amount due, amount paid, and line items. The InvoiceID field is the Xero-internal UUID you'll need for payment recording and status updates. Display a clean invoice list with quick filters for 'Outstanding', 'Overdue', and 'Paid' statuses. For invoice creation, you need to know your Xero Contact IDs. Build a contact selector that calls get-contacts and lets the user pick from a dropdown. Xero invoice line items require: Description (free text), Quantity, UnitAmount, and AccountCode (the Xero chart of accounts code, e.g. '200' for Sales). Use a default AccountCode that makes sense for your business and allow it to be changed in advanced settings. Tip: Xero provides online invoice payment links if you have Xero payment services enabled — the invoice data includes an Url field with a payment link you can display to clients directly in your portal.

One of Xero's unique features is that a single user can be connected to multiple organizations (tenants). An accountant, for example, might manage 20 client organizations from one Xero login. Your app needs to handle this gracefully. When the OAuth2 flow completes, call GET https://api.xero.com/connections to get the list of all tenants the user has authorized your app to access. Each connection has a tenantId, tenantType ('ORGANISATION'), and tenantName. Store all connections in Supabase and let the user select which organization to work with in your app's settings. Add an organization switcher to your navigation. When the user switches organizations, update the active tenant_id in their session or database record. All subsequent Edge Function calls will use the new tenant_id in the Xero-Tenant-Id header. For accountants building tools for multiple clients, you can display all organizations in a sidebar, allowing them to view invoices and contacts across multiple Xero organizations without needing to log in and out. Each organization's data is fetched with the same access token but a different Xero-Tenant-Id header.