QuickBooks Online actions

The QuickBooks block reads and writes records in a QuickBooks Online company. For the plain-language overview, see QuickBooks Online.

When to use it

Use a QuickBooks step to create or look up customers, invoices, payments, vendor bills and journal entries, to run a QuickBooks report, or to move documents and PDFs in and out of QuickBooks. Every action in the Studio Action list has an executor, so a step built in the editor and a step written in a workflow definition run the same code.

Connection

If config.connection names a connection that no longer resolves, the run stops at that step instead of falling back to the default account.

Step settings

These fields are shared across the original actions. The Studio form shows each one only for the actions that read it.

The newer record actions (for example createEstimate or getPurchaseOrder) take Intuit's own field names:

Actions

The action id is quickbooks.<action>. All of these appear in the Studio Action list.

Behaviour worth knowing

• createBill always creates a new bill. It has no lookup by bill number, so running it twice creates two bills. Only invoices and journal entries have an upsert.
• upsertInvoiceByDocNumber and upsertJournalEntryByDocNumber first try the stored id (invoiceId or journalEntryId), then fall back to a lookup by docNumber. A match is updated, carrying the new docNumber onto the existing record; no match creates one. They return a normalized envelope (operation, invoiceId or the journal id, syncToken, docNumber, realmId and the record), not the raw QuickBooks response.
• findInvoiceByDocNumber, findJournalEntryByDocNumber return { found, id, syncToken, entity }, so a condition step can test found.
• Journal-entry lines take amount, postingType (debit or credit), and either accountId or accountNumber (resolved against the chart of accounts with one extra request). Optional: description, entityType (Customer, Vendor, Employee) with entityId, classId, departmentId. The step fails before calling QuickBooks when there are fewer than two lines, only debits or only credits, an amount that is not a number, or debits that do not equal credits.
• createPayment applies the payment to at most one invoice through invoiceIds. To split one payment across invoices, use batch with explicit Line amounts.
• Invoices billed and collected elsewhere (for example a Stripe invoice mirrored into QuickBooks) should set allowOnlineCreditCardPayment and allowOnlineACHPayment to false, so the QuickBooks copy does not offer a second way to pay. Each of these invoice fields, and emailStatus and email, reaches QuickBooks only when the step sets it, so an existing step keeps sending the request it sent before. An emailStatus outside the three values, a boolean field set to anything but true or false, or an email that is not text stops the step before QuickBooks is called. Field definitions: Intuit Invoice entity.
• A rejected write names its reason. When QuickBooks refuses a request, the step error carries Intuit's fault type, Message, Detail and code, for example Nango proxy request failed (400): ValidationFault: A business validation error has occurred while processing your request: <detail> (code 6000). The text is capped at 300 characters and scrubbed of tokens and keys.
• txnTaxDetail carries tax calculated elsewhere (for example by Avalara). Send totalTax and txnTaxCodeId together, and a taxCodeId on every line.
• PDF actions return contentBase64, contentType (application/pdf) and size. uploadAttachment takes fileName, contentType and contentBase64 (up to 20 MB) plus optional attachmentMetadata.
• batch takes 1 to 30 batchItems, each with a unique bId. Check every item in the response for Fault. changeDataCapture takes entities (up to 30 names) and a changedSince timestamp within the last 30 days.
• runReport accepts these reportType values: AccountList, AgedPayableDetail, AgedPayables, AgedReceivableDetail, AgedReceivables, BalanceSheet, CashFlow, CustomerBalance, CustomerBalanceDetail, CustomerIncome, GeneralLedger, InventoryValuationDetail, InventoryValuationSummary, JournalReport, ProfitAndLoss, ProfitAndLossDetail, ClassSales, CustomerSales, DepartmentSales, ItemSales, TaxSummary, TransactionList, TransactionListByVendor, TransactionListByCustomer, TransactionListWithSplits, TrialBalanceFR, TrialBalance, VendorBalance, VendorBalanceDetail, VendorExpenses. The output keeps the report's Header, Columns and nested Rows.

Output

Most actions return the QuickBooks response unchanged, keyed by record name, so a later step reads {{steps.<id>.Invoice.Id}}, {{steps.<id>.Bill.Id}} or {{steps.<id>.JournalEntry.Id}}. The find and upsert actions return the normalized shapes described above, so read {{steps.<id>.found}} or {{steps.<id>.invoiceId}}. Curated input and output examples for each action are in GET /api/v1/blocks/quickbooks/actions/<action>/examples.

Example

A step that posts a balanced month-end accrual. It reads the amount from an earlier step and pins a specific QuickBooks connection.

{
  "id": "post_accrual",
  "type": "action",
  "name": "Post accrual journal entry",
  "action": "quickbooks.createJournalEntry",
  "config": {
    "operation": "createJournalEntry",
    "connection": "<quickbooks-connection-id>",
    "realmId": "9341454792746027",
    "docNumber": "ACCR-2026-10",
    "txnDate": "2026-10-31",
    "privateNote": "October accrued expenses",
    "journalLines": [
      { "accountNumber": "6100", "postingType": "debit", "amount": "{{steps.estimate.total}}", "description": "Accrued expenses" },
      { "accountNumber": "2100", "postingType": "credit", "amount": "{{steps.estimate.total}}", "description": "Accrued liabilities" }
    ]
  }
}

A later step reads the new entry's id as {{steps.post_accrual.JournalEntry.Id}}.

Live catalog

GET /api/v1/blocks/quickbooks returns the block's fields, the action list and the parameter schema of each record action. See Block and action discovery.

Errors and limits

• realmId is required for QuickBooks API calls: set realmId on the step.
• <field> must be a QuickBooks identifier: ids accept letters, digits, _ and - only.
• data.Id and data.SyncToken must be valid QuickBooks identifiers: read the record first and pass its current SyncToken.
• journal entry does not balance: the debit and credit totals differ; the message shows both totals.
• QuickBooks errors are returned with Intuit's fault detail. Availability of some records (budgets, inventory, multicurrency) depends on the connected company's subscription and settings.