fix(quickbooks): support sandbox environment

Author: Bill Leoutsakos

apps/docs/content/docs/en/integrations/quickbooks.mdx

@@ -30,6 +30,7 @@ List vendors from QuickBooks Online
 | `activeOnly` | boolean | No | Only return active vendors |
 | `startPosition` | string | No | One-based start position for QuickBooks query pagination |
 | `maxResults` | string | No | Maximum number of vendors to return, up to 1000 |
+| `apiEnvironment` | string | No | QuickBooks API environment: production or sandbox. Defaults to production. |
 | `minorVersion` | string | No | QuickBooks Accounting API minor version. Defaults to 75. |
 
 #### Output
@@ -57,6 +58,7 @@ List purchase orders from QuickBooks Online
 | `realmId` | string | Yes | QuickBooks company ID returned by Intuit as realmId during OAuth |
 | `startPosition` | string | No | One-based start position for QuickBooks query pagination |
 | `maxResults` | string | No | Maximum number of purchase orders to return, up to 1000 |
+| `apiEnvironment` | string | No | QuickBooks API environment: production or sandbox. Defaults to production. |
 | `minorVersion` | string | No | QuickBooks Accounting API minor version. Defaults to 75. |
 
 #### Output
@@ -85,6 +87,7 @@ List bills from QuickBooks Online
 | `realmId` | string | Yes | QuickBooks company ID returned by Intuit as realmId during OAuth |
 | `startPosition` | string | No | One-based start position for QuickBooks query pagination |
 | `maxResults` | string | No | Maximum number of bills to return, up to 1000 |
+| `apiEnvironment` | string | No | QuickBooks API environment: production or sandbox. Defaults to production. |
 | `minorVersion` | string | No | QuickBooks Accounting API minor version. Defaults to 75. |
 
 #### Output
@@ -114,6 +117,7 @@ Run a QuickBooks Online Accounting API query
 | --------- | ---- | -------- | ----------- |
 | `realmId` | string | Yes | QuickBooks company ID returned by Intuit as realmId during OAuth |
 | `query` | string | Yes | QuickBooks SQL-like query, e.g. SELECT * FROM Vendor MAXRESULTS 10 |
+| `apiEnvironment` | string | No | QuickBooks API environment: production or sandbox. Defaults to production. |
 | `minorVersion` | string | No | QuickBooks Accounting API minor version. Defaults to 75. |
 
 #### Output

apps/sim/blocks/blocks/quickbooks.ts

@@ -101,6 +101,17 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
       placeholder: '75',
       mode: 'advanced',
     },
+    {
+      id: 'apiEnvironment',
+      title: 'Environment',
+      type: 'dropdown',
+      options: [
+        { label: 'Production', id: 'production' },
+        { label: 'Sandbox', id: 'sandbox' },
+      ],
+      value: () => 'production',
+      mode: 'advanced',
+    },
   ],
   tools: {
     access: [
@@ -118,6 +129,7 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
         startPosition: params.startPosition,
         maxResults: params.maxResults,
         query: params.query,
+        apiEnvironment: params.apiEnvironment,
         minorVersion: params.minorVersion,
       }),
     },
@@ -133,6 +145,10 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
     startPosition: { type: 'string', description: 'One-based start position for pagination' },
     maxResults: { type: 'string', description: 'Maximum number of records to return, up to 1000' },
     query: { type: 'string', description: 'QuickBooks SQL-like query to execute' },
+    apiEnvironment: {
+      type: 'string',
+      description: 'QuickBooks API environment: production or sandbox',
+    },
     minorVersion: { type: 'string', description: 'QuickBooks Accounting API minor version' },
   },
   outputs: {

apps/sim/tools/quickbooks/list_bills.ts

@@ -42,6 +42,12 @@ export const quickBooksListBillsTool: ToolConfig<QuickBooksListParams, QuickBook
       visibility: 'user-or-llm',
       description: 'Maximum number of bills to return, up to 1000',
     },
+    apiEnvironment: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'QuickBooks API environment: production or sandbox. Defaults to production.',
+    },
     minorVersion: {
       type: 'string',
       required: false,
@@ -55,6 +61,7 @@ export const quickBooksListBillsTool: ToolConfig<QuickBooksListParams, QuickBook
       buildQuickBooksQueryUrl({
         realmId: params.realmId,
         query: buildQuickBooksListQuery('Bill', params),
+        apiEnvironment: params.apiEnvironment,
         minorVersion: params.minorVersion,
       }),
     method: 'GET',

apps/sim/tools/quickbooks/list_purchase_orders.ts

@@ -45,6 +45,12 @@ export const quickBooksListPurchaseOrdersTool: ToolConfig<
       visibility: 'user-or-llm',
       description: 'Maximum number of purchase orders to return, up to 1000',
     },
+    apiEnvironment: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'QuickBooks API environment: production or sandbox. Defaults to production.',
+    },
     minorVersion: {
       type: 'string',
       required: false,
@@ -58,6 +64,7 @@ export const quickBooksListPurchaseOrdersTool: ToolConfig<
       buildQuickBooksQueryUrl({
         realmId: params.realmId,
         query: buildQuickBooksListQuery('PurchaseOrder', params),
+        apiEnvironment: params.apiEnvironment,
         minorVersion: params.minorVersion,
       }),
     method: 'GET',

apps/sim/tools/quickbooks/list_vendors.ts

@@ -49,6 +49,12 @@ export const quickBooksListVendorsTool: ToolConfig<QuickBooksListParams, QuickBo
         visibility: 'user-or-llm',
         description: 'Maximum number of vendors to return, up to 1000',
       },
+      apiEnvironment: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description: 'QuickBooks API environment: production or sandbox. Defaults to production.',
+      },
       minorVersion: {
         type: 'string',
         required: false,
@@ -62,6 +68,7 @@ export const quickBooksListVendorsTool: ToolConfig<QuickBooksListParams, QuickBo
         buildQuickBooksQueryUrl({
           realmId: params.realmId,
           query: buildQuickBooksListQuery('Vendor', params),
+          apiEnvironment: params.apiEnvironment,
           minorVersion: params.minorVersion,
         }),
       method: 'GET',

apps/sim/tools/quickbooks/query.ts

@@ -36,6 +36,12 @@ export const quickBooksQueryTool: ToolConfig<QuickBooksQueryParams, QuickBooksQu
       visibility: 'user-or-llm',
       description: 'QuickBooks SQL-like query, e.g. SELECT * FROM Vendor MAXRESULTS 10',
     },
+    apiEnvironment: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'QuickBooks API environment: production or sandbox. Defaults to production.',
+    },
     minorVersion: {
       type: 'string',
       required: false,

apps/sim/tools/quickbooks/quickbooks.test.ts

@@ -44,6 +44,28 @@ describe('QuickBooks tools', () => {
     expect(requestBody(params)).toBe('SELECT * FROM Vendor MAXRESULTS 10')
   })
 
+  it('targets the QuickBooks sandbox API host when requested', () => {
+    const query = buildQuickBooksListQuery('Bill', { maxResults: '10' })
+    const url = buildQuickBooksQueryUrl({
+      realmId: '123145',
+      query,
+      apiEnvironment: 'sandbox',
+    })
+
+    expect(url).toBe(
+      'https://sandbox-quickbooks.api.intuit.com/v3/company/123145/query?minorversion=75&query=SELECT+*+FROM+Bill+MAXRESULTS+10'
+    )
+  })
+
+  it('rejects unknown QuickBooks API environments', () => {
+    expect(() =>
+      buildQuickBooksQueryEndpoint({
+        realmId: '123145',
+        apiEnvironment: 'development',
+      })
+    ).toThrow('QuickBooks environment must be production or sandbox')
+  })
+
   it('rejects invalid pagination before calling QuickBooks', () => {
     expect(() =>
       buildQuickBooksListQuery('Bill', {

apps/sim/tools/quickbooks/types.ts

@@ -1,10 +1,12 @@
 import type { ToolResponse } from '@/tools/types'
 
 export type QuickBooksEntityName = 'Vendor' | 'PurchaseOrder' | 'Bill'
+export type QuickBooksEnvironment = 'production' | 'sandbox'
 
 export interface QuickBooksBaseParams {
   accessToken: string
   realmId: string
+  apiEnvironment?: QuickBooksEnvironment | string
   minorVersion?: string
 }
 

apps/sim/tools/quickbooks/utils.ts

@@ -1,12 +1,16 @@
 import { truncate } from '@sim/utils/string'
 import type {
   QuickBooksEntityName,
+  QuickBooksEnvironment,
   QuickBooksFault,
   QuickBooksQueryEnvelope,
   QuickBooksRecord,
 } from '@/tools/quickbooks/types'
 
-export const QUICKBOOKS_API_BASE = 'https://quickbooks.api.intuit.com'
+export const QUICKBOOKS_API_BASES: Record<QuickBooksEnvironment, string> = {
+  production: 'https://quickbooks.api.intuit.com',
+  sandbox: 'https://sandbox-quickbooks.api.intuit.com',
+}
 export const QUICKBOOKS_MINOR_VERSION = '75'
 
 const QUICKBOOKS_MAX_RESULTS_LIMIT = 1000
@@ -22,28 +26,40 @@ export function buildQuickBooksHeaders(accessToken: string): Record<string, stri
 
 export function buildQuickBooksQueryEndpoint(params: {
   realmId: string
+  apiEnvironment?: QuickBooksEnvironment | string
   minorVersion?: string
 }): string {
   const realmId = params.realmId.trim()
   if (!realmId) {
     throw new Error('QuickBooks Company ID is required')
   }
 
-  const url = new URL(`${QUICKBOOKS_API_BASE}/v3/company/${encodeURIComponent(realmId)}/query`)
+  const url = new URL(
+    `${getQuickBooksApiBase(params.apiEnvironment)}/v3/company/${encodeURIComponent(realmId)}/query`
+  )
   url.searchParams.set('minorversion', normalizeMinorVersion(params.minorVersion))
   return url.toString()
 }
 
 export function buildQuickBooksQueryUrl(params: {
   realmId: string
   query: string
+  apiEnvironment?: QuickBooksEnvironment | string
   minorVersion?: string
 }): string {
   const url = new URL(buildQuickBooksQueryEndpoint(params))
   url.searchParams.set('query', normalizeQuickBooksQuery(params.query))
   return url.toString()
 }
 
+export function getQuickBooksApiBase(environment?: QuickBooksEnvironment | string): string {
+  const normalized = environment?.trim() || 'production'
+  if (normalized === 'production' || normalized === 'sandbox') {
+    return QUICKBOOKS_API_BASES[normalized]
+  }
+  throw new Error('QuickBooks environment must be production or sandbox')
+}
+
 export function normalizeQuickBooksQuery(query: string): string {
   const trimmed = query.trim()
   if (!trimmed) {