QuickBooks – Gotchas

When using start and end date filters, QuickBooks requires both to be sent. However, the report only reflects the balance sheet situation as of the end date.

Payment method is required and must be Check or CreditCard.

On bill line items, QuickBooks returns ClassRef.name as the FullyQualifiedName (e.g. "Fruit:Apple") rather than the leaf class name. Apideck normalises this by extracting the last : segment, so tracking_categories[].name returns "Apple" and parent_name returns "Fruit". Expense line items are unaffected — QuickBooks returns only the short name there.

When creating a bill in QuickBooks, each line item must be accompanied by a type designation. If the type is set to "expense_item," an item ID is required. Conversely, if the type is "expense_account," a ledger account ID must be provided. Additionally, multicurrency needs to be enabled in your QBO account. If creating a bill in your default currency, you do not need to send the currency value as long as the supplier uses the same currency. For bills with suppliers using a different currency than your default, you must include the currency value, matching the supplier's configured currency. To change the currency of a customer or vendor, a new one must be created with the desired currency. Foreign currencies can only be sent to suppliers configured with that currency.

On bill line items, QuickBooks returns ClassRef.name as the FullyQualifiedName (e.g. "Fruit:Apple") rather than the leaf class name. Apideck normalises this by extracting the last : segment, so tracking_categories[].name returns "Apple" and parent_name returns "Fruit". Expense line items are unaffected — QuickBooks returns only the short name there.

QuickBooks supports only billing and shipping addresses. Therefore, when creating addresses, it is required to specify the type as 'billing' or 'shipping' in the address object within the addresses array.

QuickBooks supports only billing and shipping addresses. Therefore, when creating or updating addresses, it is required to specify the type as 'billing' or 'shipping' in the address object within the addresses array.

The taxable field is applicable to US companies only and should be sent in the request body if your QuickBooks account is in the US region.

The taxable field is applicable to US companies only and should be sent in the request body if your QuickBooks account is in the US region.

QuickBooks uses tax codes rather than tax rates. The tax_rate on line items references a tax code, which may not include the actual percentage value. To get the actual rate, retrieve the full tax rate details via the tax-rates endpoint.

Quickbooks offers limited (regional) support for applying discount on a Line Item. Including discount_percentage or discount_amount applies to entire invoice. The default type for a Line Item is a sales item if no type has been provided.

Quickbooks offers limited (regional) support for applying discount on a Line Item. Including discount_percentage or discount_amount applies to entire invoice. The default type for a Line Item is a sales item if no type has been provided. When setting status to void, do not include any other fields in the request body.

When setting tax rates on line items, QuickBooks requires valid tax codes. The tax_rate.id must reference an existing tax code from the tax-rates endpoint. QuickBooks automatically calculates tax amounts based on the tax code's rate.

QuickBooks only returns journal entries that were explicitly created as JournalEntry records. System-generated GL postings from invoices, bills, payments, deposits, transfers, and other transaction types post to the general ledger but are not exposed by QuickBooks as journal entries and will not appear in this response. To reconstruct full GL activity, fetch the underlying transaction resources (invoices, bills, payments, etc.) in addition to journal entries.

Quickbooks only supports one tracking category at a time so only the first item in the tracking_categories list will be used. Line-level tax fields (tax_rate, tax_amount, tax_type) on journal entries are only supported for non-US QuickBooks companies (UK, CA, AU, etc.). US-based QuickBooks companies silently discard all tax fields — the request succeeds but no tax data is persisted. For US companies that need to reflect tax in journal entries, add a separate line item posting the tax amount to a tax liability ledger account (e.g., "Sales Tax Payable"). This keeps the journal entry balanced in the general ledger, but will not populate QuickBooks Sales Tax reports — for that, use invoices or sales receipts instead. When line_items[].tax_type is not set, QuickBooks requires knowing whether the tax applies to a sales or purchase transaction. Unify infers this from line_items[].type: credit lines are treated as sales (TaxApplicableOn: Sales) and debit lines as purchases (TaxApplicableOn: Purchase). This covers the common case of sales summary journal entries. For atypical entries (e.g. a credit to an AP account, or a debit for a sales return), set tax_type explicitly on each line to override the default.

Quickbooks only supports one tracking category at a time so only the first item in the tracking_categories list will be used. When line_items[].tax_type is not set, QuickBooks requires knowing whether the tax applies to a sales or purchase transaction. Unify infers this from line_items[].type: credit lines are treated as sales (TaxApplicableOn: Sales) and debit lines as purchases (TaxApplicableOn: Purchase). This covers the common case of sales summary journal entries. For atypical entries (e.g. a credit to an AP account, or a debit for a sales return), set tax_type explicitly on each line to override the default.

This connector does not support deleting ledger accounts. Instead, it will update the ledger account to inactive.

Payment allocations in QuickBooks are processed asynchronously. While the allocations are included in the request, they may not appear in the immediate response. The allocations will be applied and become visible in subsequent list or get calls.

To clear the payment method on an existing payment, send payment_method_id: null explicitly in the PATCH body. Omitting the field preserves the existing payment method (sparse update semantics). Sending null triggers PaymentMethodRef: { value: null } in the QuickBooks sparse POST, which removes the payment method reference from the payment.

The priority field is mapped from QuickBooks integer values (0-9) to unified enum values using ranges: 0-2 → "low", 3-5 → "medium", 6-7 → "high", 8-9 → "critical".

The priority field accepts enum values ("low", "medium", "high", "critical") which are converted to QuickBooks integer values: "low" → 2, "medium" → 5, "high" → 7, "critical" → 9.

The priority field is mapped from QuickBooks integer values (0-9) to unified enum values using ranges: 0-2 → "low", 3-5 → "medium", 6-7 → "high", 8-9 → "critical".

The priority field accepts enum values ("low", "medium", "high", "critical") which are converted to QuickBooks integer values: "low" → 2, "medium" → 5, "high" → 7, "critical" → 9.

tax_inclusive only applies to UK, AU, IN, and CA editions. US companies ignore this field silently.

tax_inclusive only applies to UK, AU, IN, and CA editions. US companies ignore this field silently. payment_method_id is required to set the payment method. Provide the ID of a payment method record configured in QuickBooks. total_amount is required on each line item. If not provided, it is computed from quantity * unit_price. tracking_categories behavior depends on company settings. "One to entire transaction" uses top-level tracking_categories. "One to each row" requires tracking_categories on each line item.

tax_inclusive only applies to UK, AU, IN, and CA editions. US companies will not have this field in responses. payment_method returns the name of the payment method record, not the payment type category.

row_version is required for updates. tracking_categories behavior depends on company settings. "One to each row" requires tracking_categories on each line item.

QuickBooks only supports a single billing address. Therefore, the first item in the addresses array will always be mapped as the billing address, regardless of its original type.

QuickBooks only supports a single billing address. Therefore, the first item in the addresses array will always be mapped as the billing address, regardless of its original type.

In quickbooks, the tax rates resource does not support pagination. QuickBooks returns tax codes rather than complete tax rate data. The effective_tax_rate may not be populated; use code to reference the tax in invoice line items.

To create a tax rate, effective_tax_rate, tax_payable_account_id, name and a component is required. If tax_payable_account_id is unknown, make a proxy call to get list of TaxAgency. TaxAgency doc