How to Integrate Bolt.new with QuickBooks Online

Before writing any code, you need to register your application with Intuit's developer platform. Go to developer.intuit.com and sign in with your Intuit account (or create a free one — no QuickBooks subscription required for the sandbox environment). Click 'Create an app', select 'QuickBooks Online and Payments', give your app a name, and click 'Create app'. In your app's dashboard, navigate to the Keys & credentials section. You will see two environments: Sandbox and Production. Start with Sandbox — it comes with pre-populated test data. Copy the Client ID and Client Secret for the Sandbox environment. Now configure the redirect URI. This is the URL where Intuit sends users back to your app after they authorize access. In the Redirect URIs section, add two URIs: your deployed app's URL (e.g., https://your-app.netlify.app/api/quickbooks/callback) for production testing, and http://localhost:3000/api/quickbooks/callback for local development. You can add both and QuickBooks will accept either. The scopes you need depend on your use case. For reading and writing invoices and customers, request: com.intuit.quickbooks.accounting. For payment processing, add com.intuit.quickbooks.payment. Start with just the accounting scope and add more later if needed. Write down the exact scope string — you will need it in your authorization URL.

1// .env.local
2QUICKBOOKS_CLIENT_ID=your_sandbox_client_id
3QUICKBOOKS_CLIENT_SECRET=your_sandbox_client_secret
4QUICKBOOKS_REDIRECT_URI=https://your-app.netlify.app/api/quickbooks/callback
5QUICKBOOKS_ENVIRONMENT=sandbox

The QuickBooks OAuth 2.0 flow has two legs. First, your app redirects the user to Intuit's authorization page where they log in and grant access. Second, Intuit redirects back to your callback URL with an authorization code, which your server exchanges for access and refresh tokens. Both legs must happen server-side to keep your client secret secure. Create two Next.js API routes: one at app/api/quickbooks/authorize/route.ts that constructs the authorization URL and redirects the user, and one at app/api/quickbooks/callback/route.ts that handles the redirect from Intuit. The callback route receives the authorization code as a query parameter and exchanges it for tokens by making a POST request to Intuit's token endpoint. The access token expires after one hour. The refresh token is valid for 100 days for Sandbox and 100 days for Production. Your app needs to store both tokens (along with the expiry time and the realmId, which identifies the QuickBooks company) and implement token refresh logic before making API calls. For a production app, store tokens in your database. For a prototype, storing in a server-side session or encrypted cookie is sufficient. Important: the OAuth callback CANNOT be tested in Bolt's WebContainer preview because the WebContainer cannot receive incoming HTTP requests from Intuit's servers. Deploy to Netlify or Vercel first, add the deployed URL as a redirect URI in your Intuit developer app, and test the auth flow on the deployed site.

1// app/api/quickbooks/authorize/route.ts
2import { NextResponse } from 'next/server';
3
4export async function GET() {
5  const clientId = process.env.QUICKBOOKS_CLIENT_ID;
6  const redirectUri = process.env.QUICKBOOKS_REDIRECT_URI;
7  const scope = 'com.intuit.quickbooks.accounting';
8  const state = Math.random().toString(36).substring(2);
9
10  const authUrl = new URL('https://appcenter.intuit.com/connect/oauth2');
11  authUrl.searchParams.set('client_id', clientId!);
12  authUrl.searchParams.set('redirect_uri', redirectUri!);
13  authUrl.searchParams.set('response_type', 'code');
14  authUrl.searchParams.set('scope', scope);
15  authUrl.searchParams.set('state', state);
16
17  return NextResponse.redirect(authUrl.toString());
18}
19
20// app/api/quickbooks/callback/route.ts
21import { NextRequest, NextResponse } from 'next/server';
22
23export async function GET(request: NextRequest) {
24  const { searchParams } = new URL(request.url);
25  const code = searchParams.get('code');
26  const realmId = searchParams.get('realmId');
27
28  if (!code || !realmId) {
29    return NextResponse.json({ error: 'Missing code or realmId' }, { status: 400 });
30  }
31
32  const clientId = process.env.QUICKBOOKS_CLIENT_ID!;
33  const clientSecret = process.env.QUICKBOOKS_CLIENT_SECRET!;
34  const redirectUri = process.env.QUICKBOOKS_REDIRECT_URI!;
35  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
36
37  const tokenResponse = await fetch('https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer', {
38    method: 'POST',
39    headers: {
40      'Authorization': `Basic ${credentials}`,
41      'Content-Type': 'application/x-www-form-urlencoded',
42    },
43    body: new URLSearchParams({
44      grant_type: 'authorization_code',
45      code,
46      redirect_uri: redirectUri,
47    }).toString(),
48  });
49
50  const tokens = await tokenResponse.json();
51  // In production, store tokens and realmId in your database
52  // For now, return them to confirm the flow works
53  return NextResponse.json({ success: true, realmId, expiresIn: tokens.expires_in });
54}

With tokens in hand, you can now call the QuickBooks REST API. All QuickBooks API calls follow the same URL pattern: https://quickbooks.api.intuit.com/v3/company/{realmId}/{resource}. For Sandbox, use https://sandbox-quickbooks.api.intuit.com/v3/company/{realmId}/{resource}. Always include the minorversion=70 query parameter to use the current API version and get consistent field names. The QuickBooks API uses a SQL-like query language called the QuickBooks Query Language (QBQL) for listing and filtering records. To fetch all customers, you POST or GET a query like SELECT * FROM Customer WHERE Active = true MAXRESULTS 100. To fetch open invoices, use SELECT * FROM Invoice WHERE Balance > '0.00'. Create server-side API routes in your Next.js app that accept requests from your React components, retrieve the stored QuickBooks tokens, check if the access token has expired (access tokens last one hour), refresh if needed, and then make the QuickBooks API call. This pattern keeps credentials server-side and out of the browser. The response format is consistent: each resource comes back as a JSON object with a QueryResponse wrapper containing the resource name as a key (e.g., QueryResponse.Customer for customer queries, QueryResponse.Invoice for invoice queries) and TotalCount indicating the total number of matching records.

1// app/api/quickbooks/invoices/route.ts
2import { NextResponse } from 'next/server';
3
4// In production, retrieve these from your database/session
5const REALM_ID = process.env.QUICKBOOKS_REALM_ID;
6const ACCESS_TOKEN = process.env.QUICKBOOKS_ACCESS_TOKEN; // For demo only
7const IS_SANDBOX = process.env.QUICKBOOKS_ENVIRONMENT === 'sandbox';
8
9const QB_BASE_URL = IS_SANDBOX
10  ? `https://sandbox-quickbooks.api.intuit.com/v3/company/${REALM_ID}`
11  : `https://quickbooks.api.intuit.com/v3/company/${REALM_ID}`;
12
13export async function GET() {
14  const query = "SELECT * FROM Invoice WHERE Balance > '0.00' MAXRESULTS 100";
15
16  const response = await fetch(
17    `${QB_BASE_URL}/query?query=${encodeURIComponent(query)}&minorversion=70`,
18    {
19      headers: {
20        'Authorization': `Bearer ${ACCESS_TOKEN}`,
21        'Accept': 'application/json',
22      },
23    }
24  );
25
26  if (!response.ok) {
27    const error = await response.json();
28    return NextResponse.json({ error }, { status: response.status });
29  }
30
31  const data = await response.json();
32  const invoices = data.QueryResponse?.Invoice ?? [];
33
34  return NextResponse.json({
35    invoices,
36    total: data.QueryResponse?.totalCount ?? 0,
37  });
38}

Creating an invoice in QuickBooks via the API requires a POST request to the invoice endpoint with a JSON body that includes at minimum: the customer reference (CustomerRef with the QuickBooks customer ID), at least one line item (Line array), and a currency code. The QuickBooks API is strict about required fields — missing any required field returns a 400 error with a descriptive error code in the response body. Each line item in the Line array needs a DetailType of SalesItemLineDetail (for product/service items), an Amount (the total for that line), and a SalesItemLineDetail object with ItemRef (the QuickBooks item ID) and Qty and UnitPrice. If you do not have an ItemRef, you can use DetailType: SubTotalLineDetail for simple amount lines, but using actual QuickBooks items is preferred for proper P&L categorization. The most common creation error is using a CustomerRef.value that does not exist in QuickBooks. Always fetch the customer list first and match by name or email before attempting invoice creation. Similarly, ItemRef values must correspond to actual items in your QuickBooks Items list — fetch them with SELECT * FROM Item WHERE Type = 'Service'. Rate limiting note: the QuickBooks API allows 500 requests per minute per realm. For bulk invoice creation (e.g., generating 100 invoices from a CSV upload), add a 120ms delay between requests or batch process in groups with pauses to stay safely under the limit.

1// app/api/quickbooks/invoices/create/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const REALM_ID = process.env.QUICKBOOKS_REALM_ID;
5const ACCESS_TOKEN = process.env.QUICKBOOKS_ACCESS_TOKEN;
6const IS_SANDBOX = process.env.QUICKBOOKS_ENVIRONMENT === 'sandbox';
7
8const QB_BASE_URL = IS_SANDBOX
9  ? `https://sandbox-quickbooks.api.intuit.com/v3/company/${REALM_ID}`
10  : `https://quickbooks.api.intuit.com/v3/company/${REALM_ID}`;
11
12interface LineItem {
13  description: string;
14  quantity: number;
15  unitPrice: number;
16  itemId: string; // QuickBooks Item ID
17}
18
19export async function POST(request: NextRequest) {
20  const { customerId, lineItems, dueDate } = await request.json() as {
21    customerId: string;
22    lineItems: LineItem[];
23    dueDate: string; // YYYY-MM-DD
24  };
25
26  const invoiceBody = {
27    CustomerRef: { value: customerId },
28    DueDate: dueDate,
29    Line: lineItems.map((item) => ({
30      DetailType: 'SalesItemLineDetail',
31      Amount: item.quantity * item.unitPrice,
32      Description: item.description,
33      SalesItemLineDetail: {
34        ItemRef: { value: item.itemId },
35        Qty: item.quantity,
36        UnitPrice: item.unitPrice,
37      },
38    })),
39  };
40
41  const response = await fetch(`${QB_BASE_URL}/invoice?minorversion=70`, {
42    method: 'POST',
43    headers: {
44      'Authorization': `Bearer ${ACCESS_TOKEN}`,
45      'Content-Type': 'application/json',
46      'Accept': 'application/json',
47    },
48    body: JSON.stringify(invoiceBody),
49  });
50
51  if (!response.ok) {
52    const error = await response.json();
53    return NextResponse.json(
54      { error: error.Fault?.Error?.[0]?.Message ?? 'Invoice creation failed' },
55      { status: response.status }
56    );
57  }
58
59  const data = await response.json();
60  return NextResponse.json({
61    invoiceId: data.Invoice.Id,
62    docNumber: data.Invoice.DocNumber,
63    total: data.Invoice.TotalAmt,
64  });
65}