QuickBooks

Go to developer.intuit.com and sign in with your Intuit account. Click the Dashboard tab, then click Create an App. Select QuickBooks Online and Payments as the platform. Name your app, then select the scopes you need: com.intuit.quickbooks.accounting covers invoices, expenses, accounts, and most of what a dashboard needs. Once the app is created, open its Keys & Credentials tab. You will see a Client ID and Client Secret for both Sandbox and Production environments. The Sandbox client ID and secret connect to Intuit's free Sandbox environment — use these during all development so you never affect real accounting data. Paste the Sandbox client ID and client secret somewhere safe — you will need them in Step 2 when deploying the proxy. Never paste them into FlutterFlow. In the Redirect URIs section, add the redirect URI that your proxy's OAuth callback will use. If you are using a Firebase Cloud Function, this might be something like https://us-central1-YOUR-PROJECT-ID.cloudfunctions.net/quickbooksCallback. Intuit requires this URI to be registered before the OAuth flow will work — a mismatch returns an 'invalid_request' error from Intuit's auth server. Also note the Sandbox base URL for QuickBooks API requests: sandbox-quickbooks.api.intuit.com. You will use this in the proxy during development and switch to quickbooks.api.intuit.com for production.

Your Firebase Cloud Function (or Supabase Edge Function) needs to do three things: (1) redirect the user to Intuit's authorization URL so they can approve the connection, (2) receive the OAuth callback with the authorization code and exchange it for an access token and refresh token, and (3) on every subsequent API request, use the stored access token and refresh it when it expires — always writing the new refresh token back to storage immediately. The Authorization URL you redirect to is: https://appcenter.intuit.com/connect/oauth2 with parameters: client_id, redirect_uri, response_type=code, scope, and state (a random CSRF token you generate and verify). When the user approves, Intuit redirects to your redirect_uri with code and realmId parameters. Your callback function exchanges the code for tokens by POSTing to https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer with client_id:client_secret as Basic auth and the code in the body. The most critical step: after token exchange, store the access_token, refresh_token, AND the realmId in a Firestore document keyed to the user or company. When the access token expires, POST to the same token endpoint with grant_type=refresh_token and your current refresh_token. Intuit returns a new access_token AND a new refresh_token — write both back to Firestore immediately before using the new access token. If you fail to persist the new refresh_token, the next refresh will fail because the old one is already invalidated.

1// Firebase Cloud Function proxy — index.js (simplified)
2const functions = require('firebase-functions');
3const admin = require('firebase-admin');
4const axios = require('axios');
5admin.initializeApp();
6
7const QB_TOKEN_URL = 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer';
8const QB_BASE_URL = 'https://sandbox-quickbooks.api.intuit.com'; // switch to production for live
9
10// Exchange refresh token for new tokens; always persist the new refresh_token
11async function refreshQBTokens(userId) {
12  const doc = await admin.firestore().doc(`qb_sessions/${userId}`).get();
13  const { refresh_token, realm_id } = doc.data();
14  const cfg = functions.config().quickbooks;
15  const basicAuth = Buffer.from(`${cfg.client_id}:${cfg.client_secret}`).toString('base64');
16  const resp = await axios.post(QB_TOKEN_URL,
17    `grant_type=refresh_token&refresh_token=${encodeURIComponent(refresh_token)}`,
18    { headers: { Authorization: `Basic ${basicAuth}`, 'Content-Type': 'application/x-www-form-urlencoded' } }
19  );
20  // CRITICAL: always write BOTH new tokens back before using them
21  await admin.firestore().doc(`qb_sessions/${userId}`).update({
22    access_token: resp.data.access_token,
23    refresh_token: resp.data.refresh_token,  // new refresh token — replaces old one
24    updated: Date.now(),
25  });
26  return { access_token: resp.data.access_token, realm_id };
27}
28
29// Fetch invoices from QuickBooks — proxied through this function
30exports.qbGetInvoices = functions.https.onCall(async (data, context) => {
31  const userId = context.auth?.uid || 'default';
32  let session = (await admin.firestore().doc(`qb_sessions/${userId}`).get()).data();
33  let { access_token, realm_id } = session;
34  try {
35    const resp = await axios.get(
36      `${QB_BASE_URL}/v3/company/${realm_id}/query?query=SELECT * FROM Invoice MAXRESULTS 50&minorversion=65`,
37      { headers: { Authorization: `Bearer ${access_token}`, Accept: 'application/json' } }
38    );
39    return { invoices: resp.data.QueryResponse.Invoice || [] };
40  } catch (err) {
41    if (err.response?.status === 401) {
42      // Token expired — refresh and retry once
43      const refreshed = await refreshQBTokens(userId);
44      const retry = await axios.get(
45        `${QB_BASE_URL}/v3/company/${refreshed.realm_id}/query?query=SELECT * FROM Invoice MAXRESULTS 50&minorversion=65`,
46        { headers: { Authorization: `Bearer ${refreshed.access_token}`, Accept: 'application/json' } }
47      );
48      return { invoices: retry.data.QueryResponse.Invoice || [] };
49    }
50    throw err;
51  }
52});

The realmId is QuickBooks' identifier for a specific company account. It appears in the URL when a user is logged into QuickBooks Online (the number in the URL path, e.g., /app/yourcompany?id=1234567890), and Intuit also includes it as a realmId query parameter in the OAuth callback redirect URL when the user approves your app connection. In your OAuth callback function (Step 2), extract the realmId from the callback query parameters alongside the authorization code. Store it in the Firestore document for this user or company: { access_token, refresh_token, realm_id: realmId, connected_at: Date.now() }. Every QuickBooks API request in your proxy will embed this realmId in the URL path: /v3/company/{realmId}/invoice, /v3/company/{realmId}/query, and so on. Without the correct realmId, QuickBooks returns an authorization error that looks like a credential problem, not a missing-ID problem — which is why it is easy to miss. If your app supports multiple connected companies (e.g., an accountant managing several QuickBooks accounts), store each company's realmId separately keyed to a company ID or user ID. Pass a companyId parameter to your proxy functions so they fetch the correct realmId from Firestore for each request. For a single-company app (e.g., a business owner's own QuickBooks), you only ever store one realmId. In FlutterFlow, add a one-time screen or deep link handler that the user visits after completing the OAuth flow in a WebView or browser. This screen receives the completion signal from your proxy (e.g., a Firestore document update showing connected: true) and navigates to the main dashboard. Use a FlutterFlow Firebase Realtime Listener on the connection status document to detect when the OAuth flow completes in the background browser tab.

1// Extract realmId in the OAuth callback function
2exports.quickbooksCallback = functions.https.onRequest(async (req, res) => {
3  const { code, realmId, state } = req.query;
4  // TODO: verify state against stored CSRF token
5  const cfg = functions.config().quickbooks;
6  const basicAuth = Buffer.from(`${cfg.client_id}:${cfg.client_secret}`).toString('base64');
7  const tokenResp = await axios.post(QB_TOKEN_URL,
8    `grant_type=authorization_code&code=${code}&redirect_uri=${encodeURIComponent(cfg.redirect_uri)}`,
9    { headers: { Authorization: `Basic ${basicAuth}`, 'Content-Type': 'application/x-www-form-urlencoded' } }
10  );
11  // Store tokens AND realmId together — both are required for every subsequent API call
12  await admin.firestore().doc(`qb_sessions/default`).set({
13    access_token: tokenResp.data.access_token,
14    refresh_token: tokenResp.data.refresh_token,
15    realm_id: realmId,   // CRITICAL: store this from the callback, not from elsewhere
16    connected: true,
17    connected_at: Date.now(),
18  });
19  res.send('<h1>QuickBooks connected! You can close this window.</h1>');
20});

With the proxy running and realmId stored, configure FlutterFlow to talk to your proxy. Click API Calls in the left navigation panel, then click + Add → Create API Group. Name it QuickBooksProxy. Set the Base URL to your Firebase Functions base URL: https://us-central1-YOUR-PROJECT-ID.cloudfunctions.net. Add a first API Call inside the group: name it GetInvoices. Set method to POST (Firebase callable functions use POST). Set the endpoint path to /qbGetInvoices. In the Body tab, add a JSON body: {} — the proxy handles everything else. In the Variables tab, you can add optional variables like maxResults (Integer, default 50) or statusFilter (String) that get passed to the proxy for more specific queries. Switch to Response & Test and paste a sample QuickBooks invoice response (see the code block below). Click Generate JSON Paths. FlutterFlow will create paths like $.invoices[0].DocNumber, $.invoices[0].TotalAmt, $.invoices[0].Balance, $.invoices[0].CustomerRef.name. Create a Data Type called QBInvoice with fields: docNumber (String), customerName (String), totalAmount (Decimal), balance (Decimal), status (String), dueDate (String). Map the JSON paths to this Data Type. Repeat this process to add a GetExpenses API Call and a GetBalances API Call as your app needs them. Each proxied call follows the same pattern: POST to the function name, parse the response, map to a Data Type.

1// Paste as sample in FlutterFlow Response & Test tab for GetInvoices
2{
3  "invoices": [
4    {
5      "Id": "1001",
6      "DocNumber": "INV-1001",
7      "TxnDate": "2025-01-10",
8      "DueDate": "2025-02-10",
9      "TotalAmt": 2500.00,
10      "Balance": 2500.00,
11      "CustomerRef": {
12        "value": "58",
13        "name": "Acme Corp"
14      },
15      "EmailStatus": "EmailSent"
16    }
17  ]
18}

Add a new Screen called Invoices. Add a ListView widget. Set its Backend Query to the QuickBooksProxy/GetInvoices API Call. Set the list's data source to your QBInvoice Data Type. FlutterFlow automatically calls the proxy when this screen loads. Inside the ListView item template, add a Container with a card-style decoration (border radius 12, a light shadow, white background). Inside, add a Column containing: a Text widget showing the customer name (bound to QBInvoice.customerName), a Row with a Text widget for the invoice number (QBInvoice.docNumber) and a Text widget for the due date (QBInvoice.dueDate), and a Row showing the total amount and the outstanding balance side by side. Use a conditional color on the balance Text — red if QBInvoice.balance is greater than 0 (unpaid), green if zero (paid). Add a summary header above the ListView: a Row with three summary cards showing total outstanding, total paid this month, and number of overdue invoices. To compute these, use FlutterFlow's List functions: apply a filter on QBInvoice.balance > 0 for outstanding, and filter by dueDate < today AND balance > 0 for overdue. These computed counts let you show dashboard totals without additional API calls. Finally, add a pull-to-refresh gesture to the ListView by wrapping it in a RefreshIndicator widget (available in FlutterFlow's component library). Bind the refresh to the GetInvoices API Call — when the user pulls down, the list re-fetches from QuickBooks through the proxy.

When you are ready to connect to live QuickBooks company data, update your proxy environment to use the Production credentials and base URL. In your Firebase Functions config, update quickbooks.client_id and quickbooks.client_secret to the Production values from your Intuit developer app. Change the QB_BASE_URL constant in your proxy from sandbox-quickbooks.api.intuit.com to quickbooks.api.intuit.com. Redeploy the functions. Run the OAuth flow again with a real QuickBooks company — the Sandbox and Production OAuth endpoints are different environments, so a fresh token exchange is required. Once the Production realmId and tokens are stored in Firestore, your existing FlutterFlow API Calls to the proxy will automatically fetch live company data without any changes in FlutterFlow itself. For ongoing operations, monitor your Firestore qb_sessions documents for a healthy updated timestamp. If the timestamp stops advancing, the refresh-token rotation has failed — likely because a concurrent proxy call tried to refresh at the same time, and both wrote back the same (now invalidated) refresh token. To prevent this, use Firestore transactions in your refresh logic so only one concurrent call can refresh at a time. Also add error handling in FlutterFlow: if the proxy returns a 'token_invalid' error, show a screen prompting the user to reconnect their QuickBooks account — this triggers the OAuth flow again and issues fresh tokens. If you'd rather hand off the entire OAuth proxy setup and maintenance to specialists, RapidDev's team builds FlutterFlow + QuickBooks integrations and handles the token lifecycle on your behalf — free scoping call at rapidevelopers.com/contact.