QuickBooks

Go to developer.intuit.com and log in with your Intuit account (or create one — it's free). Click **Dashboard** in the top navigation, then click **Create an app**. Select **QuickBooks Online and Payments** as the platform. Give your app a name (e.g. 'My Bubble Integration') and click Create app. Once created, you will land on the app's Keys & credentials page. You will see two sets of keys: **Sandbox** and **Production**. Start with Sandbox — copy the **Client ID** and **Client Secret** for the sandbox environment. You will need these for the OAuth flow. In the same Keys & credentials section, scroll down to **Redirect URIs** and click Add URI. Enter your Bubble app's callback page URL. You will create this page in the next step, so the URL will be something like `https://your-app.bubbleapps.io/qb-callback`. Click Save. Back in your Bubble app's Data tab, add these fields to the User data type: `qb_access_token` (text), `qb_refresh_token` (text), `qb_realm_id` (text), `qb_token_issued_at` (date). Then go to the **Privacy** tab, click on User, and add a rule: 'This User is Current User' — check all the new qb_ fields as readable only by the current user. This prevents QuickBooks tokens from leaking to other users.

1// Bubble User data type — new fields to add
2{
3  "qb_access_token": "text",        // Store encrypted, Privacy rule: owner only
4  "qb_refresh_token": "text",       // Same privacy rule
5  "qb_realm_id": "text",            // Company identifier, required in every API URL
6  "qb_token_issued_at": "date"      // For checking 55-minute expiry window
7}
8
9// Privacy rule (Data tab → Privacy → User):
10// When: This User is Current User
11// Read: qb_access_token, qb_refresh_token, qb_realm_id, qb_token_issued_at

The OAuth 2.0 Authorization Code flow starts by redirecting the user to Intuit's authorization page with the correct parameters. You will build this as a Bubble workflow on a 'Connect QuickBooks' button. In your Bubble page editor, add a Button element with the text 'Connect QuickBooks'. Click on the button to add a workflow. Add the action **Navigate → Open an external URL**. The URL is the QuickBooks OAuth authorization endpoint with parameters that you construct dynamically. The authorization URL format: `https://appcenter.intuit.com/connect/oauth2?client_id=[CLIENT_ID]&redirect_uri=[REDIRECT_URI]&response_type=code&scope=com.intuit.quickbooks.accounting&state=[STATE]` In Bubble's 'Open an external URL' action, build this URL as a dynamic expression: - Base: `https://appcenter.intuit.com/connect/oauth2` - `?client_id=` + your Intuit Client ID (put this directly in the URL or store in an App Data field) - `&redirect_uri=` + your callback page URL (URL-encoded) - `&response_type=code` - `&scope=com.intuit.quickbooks.accounting` - `&state=` + a unique value (can use Current User's Unique ID) to prevent CSRF Set the option 'Open in a new tab' to No — you want the same tab to land on the Intuit authorization page, then redirect back to your /qb-callback page after the user grants access. Make sure the redirect_uri exactly matches what you entered in the Intuit Developer portal, including trailing slashes or their absence. A mismatch causes an 'Invalid redirect_uri' error from Intuit before any authorization happens.

1// OAuth Authorization URL (construct in Bubble workflow)
2https://appcenter.intuit.com/connect/oauth2
3  ?client_id=ABcDEfGH123456789xyz
4  &redirect_uri=https%3A%2F%2Fyour-app.bubbleapps.io%2Fqb-callback
5  &response_type=code
6  &scope=com.intuit.quickbooks.accounting
7  &state=<Current User's Unique ID>
8
9// After user authorizes, Intuit redirects to:
10https://your-app.bubbleapps.io/qb-callback
11  ?code=Q0IxMDEwMzYxMTIwNjM0
12  &state=<same_state_value>
13  &realmId=9341452234219068   ← CAPTURE THIS IMMEDIATELY

Create a new page in your Bubble app named `qb-callback`. This page handles the OAuth redirect from Intuit. When the page loads, the URL contains two critical parameters: `code` (the authorization code to exchange for tokens) and `realmId` (the QuickBooks company identifier you need to store immediately). Add a workflow to the qb-callback page: **When page is loaded → Run a Backend Workflow**. Inside the Backend Workflow (which requires a paid Bubble plan), you will: 1. Extract the `code` URL parameter using Bubble's 'Get data from page URL' → Parameter name: `code` 2. Extract the `realmId` URL parameter using 'Get data from page URL' → Parameter name: `realmId` 3. POST to the QuickBooks token endpoint to exchange the code for tokens 4. Save all results to the User record atomically The token exchange POST: - URL: `https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer` - Method: POST - Headers: `Authorization: Basic [base64(clientId:clientSecret)]`, `Content-Type: application/x-www-form-urlencoded` - Body (form-encoded): `grant_type=authorization_code&code=[code]&redirect_uri=[your_redirect_uri]` The response contains `access_token`, `refresh_token`, `token_type`, and `expires_in`. In the same Backend Workflow step, immediately save all four values plus the extracted `realmId` to Current User's record. Save `qb_token_issued_at` as the current date/time. Do NOT proceed to any other action before this save completes — the tokens are only valid once and must be persisted immediately. After saving, navigate the user to your main dashboard page: add 'Navigate to page → [dashboard page]' as the final workflow step.

1// Token exchange POST request (configure in API Connector or Backend Workflow)
2{
3  "method": "POST",
4  "url": "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer",
5  "headers": {
6    "Authorization": "Basic <base64(clientId:clientSecret)>",  // Private
7    "Content-Type": "application/x-www-form-urlencoded",
8    "Accept": "application/json"
9  },
10  "body": "grant_type=authorization_code&code=<code_from_url>&redirect_uri=<your_redirect_uri>"
11}
12
13// Successful response:
14{
15  "access_token": "eyJlbmMiOiJBMTI4Q0...",
16  "expires_in": 3600,
17  "refresh_token": "AB11686661598blahblah",
18  "refresh_token_expires_in": 8726400,
19  "token_type": "bearer"
20}
21
22// Store immediately in User record:
23// qb_access_token = response.access_token
24// qb_refresh_token = response.refresh_token
25// qb_realm_id = realmId from URL parameter  ← Do NOT forget this
26// qb_token_issued_at = Current date/time

Now configure the API Connector for the actual data endpoints. In the Bubble editor, go to **Plugins → API Connector**. Click **Add another API** and name it 'QuickBooks'. Set the base URL for sandbox: `https://sandbox-quickbooks.api.intuit.com` (switch to `https://quickbooks.api.intuit.com` for production). In the **Shared headers** section, add the `Authorization` header with value `Bearer [access_token]` where `access_token` is a parameter. Check the **Private** checkbox — this prevents the token from appearing in browser requests. Add a second shared header: `Accept: application/json` (required by QuickBooks IDS to return JSON instead of XML). Add a shared header: `Content-Type: application/json` for POST calls. Now add your first API call: click **Add a call**, name it 'Get Company Info'. Set method to GET and path to `/v3/company/[realm_id]/companyinfo/[realm_id]`. The `realm_id` parameter will be supplied at call time from the User's stored `qb_realm_id` field. Set **Use as: Data**. For the **Initialize call**, you need real values. In the test parameter fields: enter a real access_token from your test user's stored value, and enter the sandbox realmId you connected earlier. Click **Initialize call**. You should receive a 200 response with company name, address, and country. Bubble will auto-detect these fields. If you see a 401, your access_token has expired — run the token refresh workflow (built in Step 6) to get a fresh token first. If you see a 404, double-check the realm_id value matches what was stored during the OAuth callback.

1// API Connector — QuickBooks group configuration
2{
3  "api_name": "QuickBooks",
4  "base_url": "https://sandbox-quickbooks.api.intuit.com",
5  "shared_headers": [
6    {
7      "name": "Authorization",
8      "value": "Bearer <access_token>",
9      "private": true
10    },
11    {
12      "name": "Accept",
13      "value": "application/json"
14    },
15    {
16      "name": "Content-Type",
17      "value": "application/json"
18    }
19  ]
20}
21
22// Initialize Call — GET Company Info:
23{
24  "method": "GET",
25  "path": "/v3/company/<realm_id>/companyinfo/<realm_id>",
26  "use_as": "Data"
27}
28
29// Successful response shape:
30{
31  "CompanyInfo": {
32    "CompanyName": "Sandbox Company_US_2",
33    "Country": "US",
34    "SyncToken": "5",
35    "Id": "1"
36  },
37  "time": "2026-07-10T08:00:00.000-07:00"
38}

Add the invoice query call. In your QuickBooks API Connector group, click **Add a call**, name it 'Query Invoices'. Set method to GET and path to `/v3/company/[realm_id]/query`. Add a query parameter named `query` with a default value of `SELECT * FROM Invoice MAXRESULTS 50 STARTPOSITION 1`. The `realm_id` and `query` parameters will be passed from your Bubble workflows. QuickBooks uses IDS Query Language (IQL), which is SQL-like with important differences: - Entity names are **singular PascalCase**: Invoice, Customer, Payment, Bill — not invoices or customers - Pagination uses **MAXRESULTS** (not LIMIT) and **STARTPOSITION** (1-based, not 0-based) - Filtering uses standard WHERE syntax: `WHERE DueDate < '2026-01-01'` or `WHERE Balance > '0.00'` - Sort: `ORDERBY MetaData.CreateTime DESC` Initialize this call with your test values to get Bubble to detect the response shape. The response contains a `QueryResponse` object with an `Invoice` array. For creating invoices, add another call named 'Create Invoice'. Set method to POST, path to `/v3/company/[realm_id]/invoice`. The JSON body needs at minimum: `Line` (array of line items with DetailType, Amount, SalesItemLineDetail), and `CustomerRef` (Id of the customer). Set **Use as: Action** for this call since it creates data rather than returning it for display. In your Bubble Repeating Group, set Type of content to 'QuickBooks — Query Invoices — QueryResponse Invoice' (the auto-detected type from the Initialize Call). Set Data source to 'Get data from external API → QuickBooks - Query Invoices' with `realm_id` set to Current User's qb_realm_id and your desired IQL query string.

1// GET Invoice Query — API call configuration
2{
3  "method": "GET",
4  "path": "/v3/company/<realm_id>/query",
5  "params": {
6    "query": "SELECT * FROM Invoice WHERE Balance > '0.00' ORDERBY MetaData.CreateTime DESC MAXRESULTS 50 STARTPOSITION 1"
7  },
8  "use_as": "Data"
9}
10
11// Sample Invoice response shape:
12{
13  "QueryResponse": {
14    "Invoice": [
15      {
16        "Id": "1",
17        "DocNumber": "1001",
18        "TotalAmt": 150.00,
19        "Balance": 150.00,
20        "DueDate": "2026-08-01",
21        "CustomerRef": { "name": "Amy's Bird Sanctuary", "value": "1" },
22        "EmailStatus": "Delivered"
23      }
24    ],
25    "startPosition": 1,
26    "maxResults": 50,
27    "totalCount": 12
28  }
29}
30
31// POST Create Invoice — body structure
32{
33  "Line": [
34    {
35      "DetailType": "SalesItemLineDetail",
36      "Amount": 150.00,
37      "SalesItemLineDetail": {
38        "ItemRef": { "value": "1", "name": "Services" }
39      }
40    }
41  ],
42  "CustomerRef": { "value": "<customer_id>" }
43}

This step is the most critical for long-term reliability. QuickBooks access tokens expire after 1 hour. When they expire, every API call returns 401 until refreshed. QuickBooks refresh tokens rotate — each use of a refresh token generates a new refresh token and invalidates the old one simultaneously. If you refresh and fail to save the new refresh_token before your workflow continues, the user must re-authorize from scratch. In Bubble's **Backend Workflows** section (Settings → API → 'Expose as a public API' must be enabled, and this requires a paid plan), create a new API Workflow named 'Refresh QuickBooks Token'. This workflow takes no parameters — it runs on behalf of the Current User. The workflow steps: 1. **Check if refresh is needed**: Add a condition — only run if Current User's qb_token_issued_at is more than 55 minutes ago (5 minutes buffer before the 1-hour expiry). 2. **Call the token refresh endpoint**: POST to `https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer` with body `grant_type=refresh_token&refresh_token=[Current User's qb_refresh_token]`. The Authorization header must be the same base64(clientId:clientSecret) as Step 3. 3. **Save both tokens atomically — this is the critical step**: In the same workflow action that processes the token response, immediately set Current User's `qb_access_token` to the response `access_token` AND `qb_refresh_token` to the response `refresh_token` AND `qb_token_issued_at` to Current date/time. Do NOT split this into two workflow steps — if the second step fails after the first succeeds, you lose the new refresh_token permanently. 4. **Call this workflow at the start of any workflow that touches QuickBooks**: Add 'Run Backend Workflow → Refresh QuickBooks Token' as the first action in any workflow that makes a QuickBooks API call. Bubble will wait for it to complete before continuing. RapidDev's team has built Bubble apps with complex OAuth token flows like this one. If you want a free architecture review before going live, visit rapidevelopers.com/contact.

1// Token Refresh POST request
2{
3  "method": "POST",
4  "url": "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer",
5  "headers": {
6    "Authorization": "Basic <base64(clientId:clientSecret)>",
7    "Content-Type": "application/x-www-form-urlencoded",
8    "Accept": "application/json"
9  },
10  "body": "grant_type=refresh_token&refresh_token=<Current User's qb_refresh_token>"
11}
12
13// Refresh response — SAME shape as initial token exchange:
14{
15  "access_token": "eyJlbmMiOiJBMTI4Q0...",  // NEW access token
16  "expires_in": 3600,
17  "refresh_token": "AB11686661598newtoken",  // NEW refresh token — save this NOW
18  "refresh_token_expires_in": 8726400,
19  "token_type": "bearer"
20}
21
22// Atomic save — BOTH tokens in one Make Changes to Current User step:
23// qb_access_token = API response.access_token
24// qb_refresh_token = API response.refresh_token   ← CRITICAL: save the new one
25// qb_token_issued_at = Current date/time