fix(quickbooks): align entity and attachment contracts

Author: Bill Leoutsakos

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

@@ -10,6 +10,17 @@ import { BlockInfoCard } from "@/components/ui/block-info-card"
   color="#2CA01C"
 />
 
+{/* MANUAL-CONTENT-START:intro */}
+## Setup
+
+Connect QuickBooks with OAuth 2.0, then enter the `realmId` for the company you authorized. Intuit returns this company ID as the `realmId` query parameter during the OAuth callback. Use a sandbox company ID with sandbox credentials and a production company ID with production credentials.
+
+QuickBooks Online does not provide a permanent API key or static per-user token for Accounting API access. Access tokens expire and are renewed through the connected OAuth credential.
+
+Entity availability can depend on the QuickBooks locale or subscription. For example, `TaxPayment` is limited to supported non-US locales, `JournalCode` is France-only, `RecurringTransaction` requires Essentials, Plus, or Advanced, and `InventoryAdjustment` requires a supported US Plus or Advanced company.
+{/* MANUAL-CONTENT-END */}
+
+
 ## Usage Instructions
 
 Integrate QuickBooks Online into procurement and accounting workflows. Manage supported records, inventory adjustments, preferences, currencies, reports, attachments, PDFs, change-data-capture syncs, batches, and custom queries.
@@ -477,14 +488,14 @@ Update a supported QuickBooks Online accounting record
 
 ### `quickbooks_upload_attachment`
 
-Upload and link a file to a QuickBooks transaction or list entity
+Upload and link a supported file up to 25 MB to a QuickBooks transaction or item
 
 #### Input
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `realmId` | string | Yes | QuickBooks company ID returned by Intuit as realmId during OAuth |
-| `file` | file | Yes | File to upload and link in QuickBooks |
+| `file` | file | Yes | Supported attachment file up to 25 MB to upload and link in QuickBooks |
 | `entity` | string | Yes | QuickBooks entity type to link the attachment to |
 | `entityId` | string | Yes | QuickBooks entity ID to link the attachment to |
 | `note` | string | No | Optional note stored with the attachment |

apps/sim/app/api/tools/quickbooks/upload-attachment/route.test.ts

@@ -152,6 +152,60 @@ describe('POST /api/tools/quickbooks/upload-attachment', () => {
     )
   })
 
+  it('rejects unsupported linked entity types before downloading the file', async () => {
+    const response = await POST(
+      createMockRequest('POST', {
+        ...baseBody,
+        entity: 'CompanyInfo',
+      })
+    )
+
+    expect(response.status).toBe(400)
+    await expect(response.json()).resolves.toEqual({
+      success: false,
+      error: 'QuickBooks entity "CompanyInfo" cannot be linked to an attachment',
+    })
+    expect(mockDownloadFileFromStorage).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
+  })
+
+  it('rejects file types outside the QuickBooks attachment whitelist', async () => {
+    mockProcessFilesToUserFiles.mockReturnValueOnce([
+      {
+        ...baseBody.file,
+        key: 'uploads/archive.zip',
+        name: 'archive.zip',
+        type: 'application/zip',
+      },
+    ])
+
+    const response = await POST(createMockRequest('POST', baseBody))
+
+    expect(response.status).toBe(400)
+    await expect(response.json()).resolves.toEqual({
+      success: false,
+      error: 'QuickBooks does not support .zip attachment files',
+    })
+    expect(mockDownloadFileFromStorage).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
+  })
+
+  it('rejects resolved content types that do not match the file extension', async () => {
+    mockDownloadFileFromStorage.mockResolvedValueOnce({
+      buffer: Buffer.from('not-a-pdf'),
+      contentType: 'text/plain',
+    })
+
+    const response = await POST(createMockRequest('POST', baseBody))
+
+    expect(response.status).toBe(400)
+    await expect(response.json()).resolves.toEqual({
+      success: false,
+      error: 'QuickBooks does not support text/plain content for .pdf attachments',
+    })
+    expect(mockFetch).not.toHaveBeenCalled()
+  })
+
   it('rejects nested QuickBooks upload faults returned with HTTP 200', async () => {
     mockFetch.mockResolvedValueOnce(
       new Response(
@@ -193,16 +247,16 @@ describe('POST /api/tools/quickbooks/upload-attachment', () => {
     })
   })
 
-  it('rejects files over the QuickBooks 100 MB attachment limit', async () => {
+  it('rejects files over the buffered 25 MB attachment limit', async () => {
     mockProcessFilesToUserFiles.mockReturnValueOnce([
-      { ...baseBody.file, size: 100 * 1024 * 1024 + 1 },
+      { ...baseBody.file, size: 25 * 1024 * 1024 + 1 },
     ])
 
     const response = await POST(createMockRequest('POST', baseBody))
     expect(response.status).toBe(400)
     await expect(response.json()).resolves.toMatchObject({
       success: false,
-      error: expect.stringContaining('100MB'),
+      error: expect.stringContaining('25MB'),
     })
     expect(mockFetch).not.toHaveBeenCalled()
   })

apps/sim/app/api/tools/quickbooks/upload-attachment/route.ts

@@ -1,3 +1,4 @@
+import { extname } from 'node:path'
 import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
 import { type NextRequest, NextResponse } from 'next/server'
@@ -22,19 +23,60 @@ import {
 export const dynamic = 'force-dynamic'
 
 const logger = createLogger('QuickBooksUploadAttachmentAPI')
-const QUICKBOOKS_MAX_UPLOAD_BYTES = 100 * 1024 * 1024
+const QUICKBOOKS_MAX_UPLOAD_BYTES = 25 * 1024 * 1024
+const QUICKBOOKS_ATTACHMENT_CONTENT_TYPES: Record<string, readonly string[]> = {
+  ai: ['application/postscript'],
+  csv: ['text/csv'],
+  doc: ['application/msword'],
+  docx: ['application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
+  eps: ['application/postscript'],
+  gif: ['image/gif'],
+  jpeg: ['image/jpeg'],
+  jpg: ['image/jpeg', 'image/jpg'],
+  ods: ['application/vnd.oasis.opendocument.spreadsheet'],
+  pdf: ['application/pdf'],
+  png: ['image/png'],
+  rtf: ['application/rtf', 'text/rtf'],
+  tif: ['image/tiff'],
+  txt: ['text/plain'],
+  xls: ['application/vnd.ms-excel'],
+  xlsx: ['application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
+  xml: ['application/xml', 'text/xml'],
+}
 
 function uploadSizeError(bytes: number): NextResponse {
   const sizeMb = (bytes / (1024 * 1024)).toFixed(2)
   return NextResponse.json(
     {
       success: false,
-      error: `File size (${sizeMb}MB) exceeds QuickBooks attachment limit of 100MB`,
+      error: `File size (${sizeMb}MB) exceeds Sim's QuickBooks attachment limit of 25MB`,
     },
     { status: 400 }
   )
 }
 
+function attachmentValidationError(error: unknown): NextResponse {
+  return NextResponse.json(
+    { success: false, error: getErrorMessage(error, 'Invalid QuickBooks attachment') },
+    { status: 400 }
+  )
+}
+
+function validateQuickBooksAttachmentFile(fileName: string, contentType?: string): void {
+  const extension = extname(fileName).slice(1).toLowerCase()
+  const allowedContentTypes = QUICKBOOKS_ATTACHMENT_CONTENT_TYPES[extension]
+  if (!allowedContentTypes) {
+    throw new Error(`QuickBooks does not support .${extension || 'unknown'} attachment files`)
+  }
+
+  const normalizedContentType = contentType?.split(';', 1)[0]?.trim().toLowerCase()
+  if (normalizedContentType && !allowedContentTypes.includes(normalizedContentType)) {
+    throw new Error(
+      `QuickBooks does not support ${normalizedContentType} content for .${extension} attachments`
+    )
+  }
+}
+
 export const POST = withRouteHandler(async (request: NextRequest) => {
   const authResult = await checkInternalAuth(request, { requireWorkflowId: false })
   if (!authResult.success || !authResult.userId) {
@@ -57,6 +99,13 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
   const denied = await assertToolFileAccess(userFile.key, authResult.userId, requestId, logger)
   if (denied) return denied
   if (userFile.size > QUICKBOOKS_MAX_UPLOAD_BYTES) return uploadSizeError(userFile.size)
+  let entity: ReturnType<typeof normalizeQuickBooksAttachmentEntity>
+  try {
+    entity = normalizeQuickBooksAttachmentEntity(params.entity)
+    validateQuickBooksAttachmentFile(userFile.name, userFile.type)
+  } catch (error) {
+    return attachmentValidationError(error)
+  }
 
   try {
     const downloaded = await downloadServableFileFromStorage(userFile, requestId, logger, {
@@ -67,7 +116,11 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     }
 
     const contentType = downloaded.contentType || userFile.type || 'application/octet-stream'
-    const entity = normalizeQuickBooksAttachmentEntity(params.entity)
+    try {
+      validateQuickBooksAttachmentFile(userFile.name, contentType)
+    } catch (error) {
+      return attachmentValidationError(error)
+    }
     const metadata = {
       AttachableRef: [
         {

apps/sim/blocks/blocks/quickbooks.test.ts

@@ -84,6 +84,14 @@ describe('QuickBooksBlock', () => {
       entityId: '17',
       file,
     })
+
+    const attachmentInputs = QuickBooksBlock.subBlocks.filter(
+      (subBlock) => subBlock.canonicalParamId === 'file'
+    )
+    expect(attachmentInputs).toMatchObject([
+      { id: 'attachmentFile', mode: 'basic', required: expect.anything() },
+      { id: 'attachmentFileRef', mode: 'advanced', required: expect.anything() },
+    ])
   })
 
   it('requires full entity payloads for non-simplified deletes', () => {
@@ -99,7 +107,14 @@ describe('QuickBooksBlock', () => {
       })
     ).toEqual({
       field: 'deleteEntity',
-      value: ['Attachable', 'Deposit', 'InventoryAdjustment', 'Transfer'],
+      value: [
+        'Attachable',
+        'CreditCardPayment',
+        'Deposit',
+        'InventoryAdjustment',
+        'RecurringTransaction',
+        'Transfer',
+      ],
     })
     expect(
       payload.required({
@@ -111,4 +126,43 @@ describe('QuickBooksBlock', () => {
       value: ['create_record', 'update_record', 'update_exchange_rate', 'update_preferences'],
     })
   })
+
+  it('exposes only documented operations for newer and locale-specific entities', () => {
+    const optionsFor = (id: string) => {
+      const subBlock = QuickBooksBlock.subBlocks.find((candidate) => candidate.id === id)
+      if (!subBlock || !('options' in subBlock) || !Array.isArray(subBlock.options)) {
+        throw new Error(`Expected ${id} entity options`)
+      }
+      return subBlock.options.map((option) => option.id)
+    }
+
+    expect(optionsFor('listEntity')).toEqual(
+      expect.arrayContaining([
+        'CreditCardPayment',
+        'TaxPayment',
+        'RecurringTransaction',
+        'JournalCode',
+      ])
+    )
+    expect(optionsFor('getEntity')).toEqual(
+      expect.arrayContaining([
+        'CreditCardPayment',
+        'TaxPayment',
+        'RecurringTransaction',
+        'JournalCode',
+      ])
+    )
+    expect(optionsFor('createEntity')).toEqual(
+      expect.arrayContaining(['CreditCardPayment', 'RecurringTransaction', 'JournalCode'])
+    )
+    expect(optionsFor('createEntity')).not.toContain('TaxPayment')
+    expect(optionsFor('updateEntity')).toContain('CreditCardPayment')
+    expect(optionsFor('updateEntity')).toContain('JournalCode')
+    expect(optionsFor('updateEntity')).not.toContain('RecurringTransaction')
+    expect(optionsFor('updateEntity')).not.toContain('TaxPayment')
+    expect(optionsFor('deleteEntity')).toContain('CreditCardPayment')
+    expect(optionsFor('deleteEntity')).toContain('RecurringTransaction')
+    expect(optionsFor('deleteEntity')).not.toContain('JournalCode')
+    expect(optionsFor('deleteEntity')).not.toContain('TaxPayment')
+  })
 })

apps/sim/blocks/blocks/quickbooks.ts

@@ -5,6 +5,7 @@ import { AuthMode, IntegrationType } from '@/blocks/types'
 import { normalizeFileInput } from '@/blocks/utils'
 import type { QuickBooksResponse } from '@/tools/quickbooks/types'
 import {
+  QUICKBOOKS_ATTACHMENT_ENTITIES,
   QUICKBOOKS_CREATABLE_ENTITIES,
   QUICKBOOKS_DELETABLE_ENTITIES,
   QUICKBOOKS_FULL_DELETE_ENTITIES,
@@ -258,14 +259,25 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
       title: 'File',
       type: 'file-upload',
       canonicalParamId: 'file',
+      mode: 'basic',
+      condition: { field: 'operation', value: 'upload_attachment' },
+      required: { field: 'operation', value: 'upload_attachment' },
+    },
+    {
+      id: 'attachmentFileRef',
+      title: 'File',
+      type: 'short-input',
+      canonicalParamId: 'file',
+      mode: 'advanced',
+      placeholder: 'Reference a file from a previous block',
       condition: { field: 'operation', value: 'upload_attachment' },
       required: { field: 'operation', value: 'upload_attachment' },
     },
     {
       id: 'attachmentEntity',
       title: 'Linked Entity Type',
       type: 'dropdown',
-      options: buildEntityOptions(QUICKBOOKS_READABLE_ENTITIES),
+      options: buildEntityOptions(QUICKBOOKS_ATTACHMENT_ENTITIES),
       value: () => 'PurchaseOrder',
       condition: { field: 'operation', value: 'upload_attachment' },
       required: { field: 'operation', value: 'upload_attachment' },
@@ -313,7 +325,11 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
       title: 'Sparse Update',
       type: 'switch',
       value: () => 'true',
-      condition: { field: 'operation', value: 'update_record' },
+      condition: {
+        field: 'operation',
+        value: 'update_record',
+        and: { field: 'updateEntity', value: 'InventoryAdjustment', not: true },
+      },
       mode: 'advanced',
     },
     {

apps/sim/lib/integrations/integrations.json

@@ -1,5 +1,5 @@
 {
-  "updatedAt": "2026-07-29",
+  "updatedAt": "2026-07-30",
   "integrations": [
     {
       "type": "onepassword",
@@ -14540,7 +14540,7 @@
         },
         {
           "name": "Upload Attachment",
-          "description": "Upload and link a file to a QuickBooks transaction or list entity"
+          "description": "Upload and link a supported file up to 25 MB to a QuickBooks transaction or item"
         },
         {
           "name": "Get Attachment URL",