fix(quickbooks): align purchasing and accounting tools with Intuit's model

Validated against Intuit's live machine-readable model files
(EntityJsonObject_v1.json, CodesModelsJsonObjects_v2.json).

- CurrencyRef is "Conditionally required" on all seven purchasing and
  accounting create models ("This must be defined if multicurrency is
  enabled for the company") and was never written, so every create failed
  on a multicurrency company. Creates now accept an ISO 4217 currencyCode.
- GlobalTaxCalculation is "Conditionally required" on Bill, VendorCredit,
  PurchaseOrder, JournalEntry, and Deposit, and Optional on Purchase
  ("Not applicable to US companies; required for non-US companies"). Those
  six creates now accept it; JournalEntry accepts only the two values
  Intuit documents for it. BillPayment has no such property and is left alone.
- Add void_bill_payment, the documented
  POST /billpayment?operation=update&include=void operation.
- itembasedexpenselinedetail.Required is [] and ItemRef is Optional, so an
  item line no longer requires itemId.
- The Deposit sparse update leaves "missing elements untouched", so
  depositAccountId is no longer forced on every update.
- BillPayment DocNumber and APAccountRef are Optional writable fields and
  were unreachable; PurchaseOrder DueDate was emitted by the body builder
  but had no parameter.
- Correct the maxResults range in the two read tools to 1-1000, matching
  validateQuickBooksPagination.
- Record the unresolved BillPayment "Line [0..n]" / requiredFlag Required
  contradiction as a TSDoc note; behavior unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RB5M2gk7zZgGomnQqr7WRB

Author: waleedlatif1

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

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildQuickBooksCreateDepositBody,
+  buildQuickBooksCreateJournalEntryBody,
+  buildQuickBooksUpdateDepositBody,
+} from '@/tools/quickbooks/accounting_utils'
+import type {
+  QuickBooksCreateDepositParams,
+  QuickBooksCreateJournalEntryParams,
+} from '@/tools/quickbooks/types'
+
+const DEPOSIT: QuickBooksCreateDepositParams = {
+  accessToken: 'token',
+  realmId: '123',
+  quickBooksEnvironment: 'sandbox',
+  depositAccountId: 'bank-1',
+  lines: [{ amount: 20, accountId: 'account-1' }],
+}
+
+const JOURNAL_ENTRY: QuickBooksCreateJournalEntryParams = {
+  accessToken: 'token',
+  realmId: '123',
+  quickBooksEnvironment: 'sandbox',
+  confirmPosting: true,
+  lines: [
+    { postingType: 'debit', amount: 20, accountId: 'account-1' },
+    { postingType: 'credit', amount: 20, accountId: 'account-2' },
+  ],
+}
+
+describe('QuickBooks multicurrency and non-US tax fields on accounting creates', () => {
+  it('emits CurrencyRef and GlobalTaxCalculation on a Deposit', () => {
+    expect(
+      buildQuickBooksCreateDepositBody({
+        ...DEPOSIT,
+        currencyCode: 'aud',
+        globalTaxCalculation: 'NotApplicable',
+      })
+    ).toMatchObject({
+      CurrencyRef: { value: 'AUD' },
+      GlobalTaxCalculation: 'NotApplicable',
+    })
+  })
+
+  it('emits CurrencyRef and GlobalTaxCalculation on a Journal Entry', () => {
+    expect(
+      buildQuickBooksCreateJournalEntryBody({
+        ...JOURNAL_ENTRY,
+        currencyCode: 'CAD',
+        globalTaxCalculation: 'TaxExcluded',
+      })
+    ).toMatchObject({
+      CurrencyRef: { value: 'CAD' },
+      GlobalTaxCalculation: 'TaxExcluded',
+    })
+  })
+
+  it('rejects NotApplicable on a Journal Entry, which Intuit does not document for it', () => {
+    expect(() =>
+      buildQuickBooksCreateJournalEntryBody({
+        ...JOURNAL_ENTRY,
+        globalTaxCalculation: 'NotApplicable',
+      })
+    ).toThrow('globalTaxCalculation must be one of TaxExcluded, TaxInclusive')
+  })
+
+  it('omits both fields when they are not supplied', () => {
+    const body = buildQuickBooksCreateDepositBody(DEPOSIT)
+
+    expect(body).not.toHaveProperty('CurrencyRef')
+    expect(body).not.toHaveProperty('GlobalTaxCalculation')
+  })
+})
+
+describe('QuickBooks Deposit sparse update', () => {
+  it('updates a single header field without restating the destination account', () => {
+    expect(
+      buildQuickBooksUpdateDepositBody({
+        accessToken: 'token',
+        realmId: '123',
+        quickBooksEnvironment: 'sandbox',
+        depositId: 'deposit-1',
+        syncToken: '2',
+        privateNote: 'Updated deposit',
+      })
+    ).toEqual({
+      Id: 'deposit-1',
+      SyncToken: '2',
+      sparse: true,
+      PrivateNote: 'Updated deposit',
+    })
+  })
+
+  it('sends DepositToAccountRef only when a replacement account is supplied', () => {
+    expect(
+      buildQuickBooksUpdateDepositBody({
+        accessToken: 'token',
+        realmId: '123',
+        quickBooksEnvironment: 'sandbox',
+        depositId: 'deposit-1',
+        syncToken: '2',
+        depositAccountId: 'bank-2',
+      })
+    ).toMatchObject({ DepositToAccountRef: { value: 'bank-2' } })
+  })
+
+  it('still refuses an update that would change nothing', () => {
+    expect(() =>
+      buildQuickBooksUpdateDepositBody({
+        accessToken: 'token',
+        realmId: '123',
+        quickBooksEnvironment: 'sandbox',
+        depositId: 'deposit-1',
+        syncToken: '2',
+      })
+    ).toThrow('Provide at least one field to update')
+  })
+})

apps/sim/tools/quickbooks/accounting_utils.ts

@@ -4,6 +4,7 @@ import type {
   QuickBooksCreateDepositParams,
   QuickBooksCreateJournalEntryParams,
   QuickBooksDepositLineInput,
+  QuickBooksGlobalTaxCalculation,
   QuickBooksJournalEntityType,
   QuickBooksJournalLineInput,
   QuickBooksJournalPostingType,
@@ -13,6 +14,8 @@ import type {
 import {
   assertQuickBooksSparseUpdate,
   optionalQuickBooksString,
+  quickBooksCurrencyRef,
+  quickBooksGlobalTaxCalculation,
   quickBooksReference,
   requiredQuickBooksString,
   validateQuickBooksDate,
@@ -29,6 +32,16 @@ const JOURNAL_LINE_KEYS = new Set([
 ])
 const DEPOSIT_LINE_KEYS = new Set(['amount', 'accountId', 'description'])
 
+/**
+ * JournalEntry is the one entity in this module whose `GlobalTaxCalculation`
+ * Intuit documents without `NotApplicable`: "Allowed values are: TaxExcluded,
+ * TaxInclusive."
+ */
+const JOURNAL_ENTRY_GLOBAL_TAX_CALCULATIONS: readonly QuickBooksGlobalTaxCalculation[] = [
+  'TaxExcluded',
+  'TaxInclusive',
+]
+
 function parseJsonArray(value: unknown, fieldName: string): unknown[] | undefined {
   if (value == null || value === '') return undefined
   let parsed = value
@@ -241,11 +254,13 @@ export function buildQuickBooksDepositLines(lines: QuickBooksDepositLineInput[])
 }
 
 function transactionHeader(params: {
+  currencyCode?: string
   transactionDate?: string
   documentNumber?: string
   privateNote?: string
 }): Record<string, unknown> {
   return filterUndefined({
+    CurrencyRef: quickBooksCurrencyRef(params.currencyCode),
     TxnDate: validateQuickBooksDate(params.transactionDate, 'transactionDate'),
     DocNumber: optionalQuickBooksString(params.documentNumber),
     PrivateNote: optionalQuickBooksString(params.privateNote),
@@ -262,10 +277,14 @@ export function buildQuickBooksCreateJournalEntryBody(
   params: QuickBooksCreateJournalEntryParams
 ): Record<string, unknown> {
   requirePostingConfirmation(params.confirmPosting)
-  return {
+  return filterUndefined({
     ...transactionHeader(params),
+    GlobalTaxCalculation: quickBooksGlobalTaxCalculation(
+      params.globalTaxCalculation,
+      JOURNAL_ENTRY_GLOBAL_TAX_CALCULATIONS
+    ),
     Line: buildQuickBooksJournalLines(params.lines),
-  }
+  })
 }
 
 export function buildQuickBooksUpdateJournalEntryBody(
@@ -285,23 +304,31 @@ export function buildQuickBooksUpdateJournalEntryBody(
 export function buildQuickBooksCreateDepositBody(
   params: QuickBooksCreateDepositParams
 ): Record<string, unknown> {
-  return {
+  return filterUndefined({
     DepositToAccountRef: quickBooksReference(params.depositAccountId, 'depositAccountId'),
     ...transactionHeader(params),
+    GlobalTaxCalculation: quickBooksGlobalTaxCalculation(params.globalTaxCalculation),
     Line: buildQuickBooksDepositLines(params.lines),
-  }
+  })
 }
 
+/**
+ * Intuit documents the Deposit sparse update as "only elements specified in the
+ * request are updated. Missing elements are left untouched", so
+ * `DepositToAccountRef` is sent only when the caller is actually changing it.
+ */
 export function buildQuickBooksUpdateDepositBody(
   params: QuickBooksUpdateDepositParams
 ): Record<string, unknown> {
-  const body = {
+  const body = filterUndefined({
     Id: requiredQuickBooksString(params.depositId, 'depositId'),
     SyncToken: requiredQuickBooksString(params.syncToken, 'syncToken'),
     sparse: true,
-    DepositToAccountRef: quickBooksReference(params.depositAccountId, 'depositAccountId'),
+    DepositToAccountRef: params.depositAccountId
+      ? quickBooksReference(params.depositAccountId, 'depositAccountId')
+      : undefined,
     ...transactionHeader(params),
-  }
-  assertQuickBooksSparseUpdate(body, 4)
+  }) as Record<string, unknown>
+  assertQuickBooksSparseUpdate(body)
   return body
 }

apps/sim/tools/quickbooks/create_bill.ts

@@ -91,6 +91,20 @@ export const quickbooksCreateBillTool: ToolConfig<
       visibility: 'user-or-llm',
       description: 'Internal bill note',
     },
+    currencyCode: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Three-letter ISO 4217 currency code, required when multicurrency is enabled for the company',
+    },
+    globalTaxCalculation: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Tax treatment required for non-US companies: TaxExcluded, TaxInclusive, or NotApplicable',
+    },
     requestId: {
       type: 'string',
       required: false,

apps/sim/tools/quickbooks/create_bill_payment.ts

@@ -81,6 +81,25 @@ export const quickbooksCreateBillPaymentTool: InternalToolConfig<
       visibility: 'user-or-llm',
       description: 'Internal payment note',
     },
+    apAccountId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Optional accounts-payable account the payment is credited to',
+    },
+    documentNumber: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Optional reference number for the payment',
+    },
+    currencyCode: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Three-letter ISO 4217 currency code, required when multicurrency is enabled for the company',
+    },
     requestId: {
       type: 'string',
       required: false,

apps/sim/tools/quickbooks/create_deposit.ts

@@ -68,6 +68,20 @@ export const quickbooksCreateDepositTool: ToolConfig<
       visibility: 'user-or-llm',
       description: 'Internal deposit note',
     },
+    currencyCode: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Three-letter ISO 4217 currency code, required when multicurrency is enabled for the company',
+    },
+    globalTaxCalculation: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Tax treatment required for non-US companies: TaxExcluded, TaxInclusive, or NotApplicable',
+    },
     requestId: {
       type: 'string',
       required: false,

apps/sim/tools/quickbooks/create_journal_entry.ts

@@ -74,6 +74,19 @@ export const quickbooksCreateJournalEntryTool: ToolConfig<
       visibility: 'user-or-llm',
       description: 'Internal journal-entry note',
     },
+    currencyCode: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Three-letter ISO 4217 currency code, required when multicurrency is enabled for the company',
+    },
+    globalTaxCalculation: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Tax treatment required for non-US companies: TaxExcluded or TaxInclusive',
+    },
     requestId: {
       type: 'string',
       required: false,

apps/sim/tools/quickbooks/create_purchase.ts

@@ -87,6 +87,20 @@ export const quickbooksCreatePurchaseTool: ToolConfig<
       visibility: 'user-or-llm',
       description: 'Internal purchase note',
     },
+    currencyCode: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Three-letter ISO 4217 currency code, required when multicurrency is enabled for the company',
+    },
+    globalTaxCalculation: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Tax treatment required for non-US companies: TaxExcluded, TaxInclusive, or NotApplicable',
+    },
     requestId: {
       type: 'string',
       required: false,

apps/sim/tools/quickbooks/create_purchase_order.ts

@@ -80,6 +80,26 @@ export const quickbooksCreatePurchaseOrderTool: ToolConfig<
       visibility: 'user-or-llm',
       description: 'Internal purchase-order note',
     },
+    currencyCode: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Three-letter ISO 4217 currency code, required when multicurrency is enabled for the company',
+    },
+    globalTaxCalculation: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Tax treatment required for non-US companies: TaxExcluded, TaxInclusive, or NotApplicable',
+    },
+    dueDate: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Date the payment is due in YYYY-MM-DD format',
+    },
     requestId: {
       type: 'string',
       required: false,

apps/sim/tools/quickbooks/create_vendor_credit.ts

@@ -80,6 +80,20 @@ export const quickbooksCreateVendorCreditTool: ToolConfig<
       visibility: 'user-or-llm',
       description: 'Internal vendor-credit note',
     },
+    currencyCode: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Three-letter ISO 4217 currency code, required when multicurrency is enabled for the company',
+    },
+    globalTaxCalculation: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Tax treatment required for non-US companies: TaxExcluded, TaxInclusive, or NotApplicable',
+    },
     requestId: {
       type: 'string',
       required: false,