Xero

Go to developer.xero.com and sign in with your Xero account. Navigate to My Apps and click New App. Choose Web app as the integration type (this enables the Authorization Code flow required for user-authorised data access). Give your app a name and enter your redirect URI — this must be the callback URL of your Firebase or Supabase proxy function. You will update this after deploying the proxy, but register a placeholder now. Once the app is created, open it and find the Client ID and Client Secret on the Configuration tab. These are the two credentials your proxy will use. Store them — you will add them to Firebase Functions config in the next step. The Client Secret is shown only once in some Xero plans; copy it immediately to a safe location. For scopes, you need at minimum: openid profile email offline_access accounting.transactions accounting.contacts accounting.settings. The offline_access scope is required to receive a refresh token — without it, the OAuth response will not include a refresh_token and the connection will expire after each access token's lifetime (~30 minutes). The accounting.transactions scope covers invoices, bills, and bank transactions. The accounting.contacts scope covers customers and vendors. Add additional scopes (accounting.reports.read, accounting.journals.read) only if your app needs them — minimal scopes are best practice.

Your Firebase Cloud Function proxy needs to handle three stages: (1) redirect the user to Xero's OAuth authorization URL, (2) receive the callback, exchange the code for tokens, then immediately call /connections to get the tenant ID, and (3) on every subsequent request, use the stored access token plus tenant ID to call the Xero API. The OAuth authorization URL is: https://login.xero.com/identity/connect/authorize with parameters: response_type=code, client_id, redirect_uri, scope (URL-encoded), and state (a CSRF nonce you generate and verify on callback). In the callback function, exchange the code for tokens by POSTing to https://identity.xero.com/connect/token with Basic auth (base64 of client_id:client_secret) and the code in an application/x-www-form-urlencoded body. Immediately after receiving the access_token, make a GET request to https://api.xero.com/connections with the access token as a Bearer header. The response is a JSON array of connected organisations; each has a tenantId and tenantName field. Extract the tenantId and store it in Firestore alongside the access_token and refresh_token. This stored tenantId becomes the Xero-tenant-id header on every future accounting API request. For token refresh, POST to https://identity.xero.com/connect/token with grant_type=refresh_token. Xero's refresh tokens do not rotate on every use (unlike QuickBooks), but they can expire — refresh when the access token returns a 401 and write the new access token to Firestore.

1// Firebase Cloud Function proxy — index.js
2const functions = require('firebase-functions');
3const admin = require('firebase-admin');
4const axios = require('axios');
5admin.initializeApp();
6
7const XERO_TOKEN_URL = 'https://identity.xero.com/connect/token';
8const XERO_API_BASE = 'https://api.xero.com/api.xro/2.0';
9const XERO_CONNECTIONS_URL = 'https://api.xero.com/connections';
10
11// OAuth callback — exchanges code for tokens, fetches tenant ID
12exports.xeroCallback = functions.https.onRequest(async (req, res) => {
13  const { code } = req.query;
14  const cfg = functions.config().xero;
15  const basicAuth = Buffer.from(`${cfg.client_id}:${cfg.client_secret}`).toString('base64');
16
17  // Exchange code for tokens
18  const tokenResp = await axios.post(XERO_TOKEN_URL,
19    `grant_type=authorization_code&code=${code}&redirect_uri=${encodeURIComponent(cfg.redirect_uri)}`,
20    { headers: { Authorization: `Basic ${basicAuth}`, 'Content-Type': 'application/x-www-form-urlencoded' } }
21  );
22  const { access_token, refresh_token } = tokenResp.data;
23
24  // CRITICAL: fetch the tenant ID immediately after receiving the access token
25  const connResp = await axios.get(XERO_CONNECTIONS_URL,
26    { headers: { Authorization: `Bearer ${access_token}` } }
27  );
28  const tenantId = connResp.data[0].tenantId;  // first connected org
29  const tenantName = connResp.data[0].tenantName;
30
31  // Store tokens + tenant ID together — all three are required for every API call
32  await admin.firestore().doc('xero/session').set({
33    access_token, refresh_token, tenant_id: tenantId, tenant_name: tenantName,
34    connected: true, updated: Date.now(),
35  });
36  res.send('<h1>Xero connected! You can close this window.</h1>');
37});
38
39// Proxy function: fetch invoices with Xero-tenant-id header
40exports.xeroGetInvoices = functions.https.onCall(async (data, context) => {
41  const doc = await admin.firestore().doc('xero/session').get();
42  const { access_token, tenant_id } = doc.data();
43  const headers = {
44    Authorization: `Bearer ${access_token}`,
45    'Xero-tenant-id': tenant_id,  // REQUIRED on every request
46    Accept: 'application/json',
47  };
48  try {
49    const resp = await axios.get(`${XERO_API_BASE}/Invoices?Statuses=AUTHORISED,DRAFT`, { headers });
50    return { invoices: resp.data.Invoices || [] };
51  } catch (err) {
52    if (err.response?.status === 401) {
53      // Refresh token and retry
54      const basicAuth = Buffer.from(`${functions.config().xero.client_id}:${functions.config().xero.client_secret}`).toString('base64');
55      const { refresh_token } = doc.data();
56      const refreshResp = await axios.post(XERO_TOKEN_URL,
57        `grant_type=refresh_token&refresh_token=${encodeURIComponent(refresh_token)}`,
58        { headers: { Authorization: `Basic ${basicAuth}`, 'Content-Type': 'application/x-www-form-urlencoded' } }
59      );
60      const newToken = refreshResp.data.access_token;
61      await admin.firestore().doc('xero/session').update({ access_token: newToken, updated: Date.now() });
62      headers.Authorization = `Bearer ${newToken}`;
63      const retry = await axios.get(`${XERO_API_BASE}/Invoices?Statuses=AUTHORISED,DRAFT`, { headers });
64      return { invoices: retry.data.Invoices || [] };
65    }
66    throw err;
67  }
68});

The /connections step in your OAuth callback returns a JSON array where each element represents one Xero organisation the user has connected. For most use cases, you work with one organisation. Extract the first element's tenantId and tenantName. If your app might have users connected to multiple Xero organisations (e.g., a bookkeeper managing several clients), store the full list of {tenantId, tenantName} pairs in Firestore and add a way for the user to select the active organisation in FlutterFlow. In FlutterFlow, add an App State variable called activeXeroOrg (String) that holds the selected tenantId. In the proxy, accept the tenantId as a request parameter rather than always reading it from Firestore — this lets the FlutterFlow app switch between organisations by passing a different tenantId. For a single-org app, hardcode the lookup to the Firestore session document. After storing the tenant ID, trigger a Firestore document write (connected: true) that your FlutterFlow app listens to. Use a FlutterFlow Firebase Realtime Listener on the xero/session document's connected field. When it flips to true, navigate the user from a 'Connecting...' screen to the main dashboard. This pattern handles the round-trip: the user opens a WebView or browser for the OAuth flow, completes it on the Xero web interface, and FlutterFlow detects the completion via the Firestore listener without the user having to tap anything.

Open your FlutterFlow project and click API Calls in the left navigation panel. Click + Add, then Create API Group. Name it XeroProxy. Set the Base URL to your Firebase Functions URL: https://us-central1-YOUR-PROJECT-ID.cloudfunctions.net. Add the first API Call: click + Add API Call, name it GetInvoices. Set method to POST (Firebase callable functions require POST). Set the path to /xeroGetInvoices. In the Body tab, set a JSON body of {} — the proxy handles authentication and tenant ID injection internally, so no parameters are needed in the body for basic calls. Add optional variables (like statusFilter or dateFrom) in the Variables tab if you want the FlutterFlow app to filter results. In the Response & Test tab, paste a sample invoice response from Xero (see the code block below). Click Generate JSON Paths. You will see paths like $.invoices[0].InvoiceID, $.invoices[0].AmountDue, $.invoices[0].Contact.Name, $.invoices[0].DueDate. Create a Data Type called XeroInvoice with fields: invoiceId (String), contactName (String), total (Decimal), amountDue (Decimal), dueDate (String), status (String). Map the JSON paths to this Data Type. Add a second API Call called GetBankTransactions following the same pattern. Add more calls for Contacts, Accounts, or Reports as your app needs them. Each call is a POST to a separate proxy function that includes the Xero-tenant-id header and handles token refresh internally.

1// Paste as sample in FlutterFlow Response & Test for GetInvoices
2{
3  "invoices": [
4    {
5      "InvoiceID": "a9fc20e6-8b98-4783-b845-b4d4b6a3cbb0",
6      "InvoiceNumber": "INV-0042",
7      "Status": "AUTHORISED",
8      "Type": "ACCREC",
9      "Total": 1800.00,
10      "AmountDue": 1800.00,
11      "DueDate": "/Date(1738022400000+0000)/",
12      "Contact": {
13        "ContactID": "b52c1f35-7c43-4a57-8c7e-1e2b5f9a3291",
14        "Name": "Smithfield Ltd"
15      }
16    }
17  ]
18}

Add a new Screen named Invoices. Add a ListView widget and set its Backend Query to XeroProxy → GetInvoices. Set the list type to XeroInvoice. FlutterFlow calls the proxy on screen load and populates the list. Inside each ListView item, add a Container with card styling (border radius 12, subtle drop shadow). Inside the Container, place a Column: a Text widget for the contact name (bound to XeroInvoice.contactName), a Row with the invoice number (XeroInvoice.invoiceId) and due date (XeroInvoice.dueDate), and a Row showing the total amount and amount due. Apply conditional formatting on the amountDue text: if amountDue equals total, the invoice is fully outstanding — show it in red. If amountDue is 0, the invoice is paid — show it in green. If amountDue is between 0 and total, it is partially paid — show in amber. Above the ListView, add a summary Row with three Container cards: Total Outstanding (sum of amountDue from all invoices with amountDue > 0), Overdue (count of invoices with dueDate before today), and Paid This Month (count of invoices with status PAID and a payment date in the current month). Use FlutterFlow's List Filters and Aggregation functions to compute these without extra API calls. Add a pull-to-refresh gesture on the ListView. Wrap it in a RefreshIndicator and bind the refresh action to GetInvoices. To avoid hitting Xero's rate limits (approximately 60 calls per minute per tenant), add logic in the proxy to cache the invoices list in Firestore for 3 minutes — subsequent GetInvoices calls within that window return the cached data without calling Xero.

Xero enforces per-tenant rate limits of approximately 60 API calls per minute and a daily call limit per tenant (check the current limits in Xero's developer documentation — verify current numbers as they may have changed). A mobile app that re-fetches invoices, contacts, and bank transactions on every screen navigation can easily exceed the per-minute limit during active use, resulting in 429 Too Many Requests errors. The solution is to cache Xero API responses in Firestore at the proxy level. When GetInvoices is called, the proxy first checks if a Firestore cache document exists and was written within the last 3 minutes. If so, it returns the cached data without calling Xero. If not, it calls Xero, writes the fresh data to Firestore cache, and returns it. This 3-minute cache window is a reasonable balance between freshness and rate-limit safety for a business that updates invoices every few hours. For 401 token expiry, the proxy's retry-with-refresh pattern from Step 2 handles the normal case transparently. However, if the Xero access token has been revoked (the user removed your app from their Xero My Apps settings), the refresh will also fail with an invalid_grant error. In this case, your proxy should return a JSON body with {"error": "authorization_revoked"} to FlutterFlow. Add a Conditional Action in FlutterFlow's GetInvoices error path: check for this error string and navigate to a Reconnect Xero screen that explains the connection was removed and prompts the user to reconnect. If you would prefer to hand the OAuth proxy setup, token management, and rate-limit caching to a team with FlutterFlow experience, RapidDev handles integrations like this every week — free scoping call at rapidevelopers.com/contact.

1// Add this caching block at the start of your xeroGetInvoices function
2const CACHE_TTL_MS = 3 * 60 * 1000; // 3 minutes
3const cacheDoc = await admin.firestore().doc('xero/cache/invoices/latest').get();
4if (cacheDoc.exists) {
5  const { data, cached_at } = cacheDoc.data();
6  if (Date.now() - cached_at < CACHE_TTL_MS) {
7    return { invoices: data, fromCache: true };
8  }
9}
10// ... call Xero API ...
11// After getting fresh data, write to cache:
12await admin.firestore().doc('xero/cache/invoices/latest').set({
13  data: freshInvoices,
14  cached_at: Date.now(),
15});