QuickBooks integration

What it does

The QuickBooks integration connects TaskJuice to your clients' QuickBooks Online company files. Once a client authorizes the connection, your workflows can create and update customers, draft, send, and void invoices, record payments, attach files, look records up by name or number, run reports, and react within about a minute when something changes inside the company file. Every read and write is scoped to the company (realm) selected during the OAuth flow, so an agency managing several bookkeeping clients keeps each client's data separate.

Connect a QuickBooks account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose QuickBooks and click Connect.
3. Sign in to Intuit with credentials that have admin access to the company file you want to manage.
4. Select the QuickBooks Online company to grant access to.
5. Approve the com.intuit.quickbooks.accounting scope.
6. TaskJuice returns to the workspace with the connection ready to use in any workflow.

To revoke access at any time, sign in to Intuit app management and disconnect TaskJuice from the company file.

Set up webhook triggers

QuickBooks sends change events to one endpoint per Intuit app, and Intuit has no API for registering it, so you set it up once by hand in the Intuit Developer portal. After that, every webhook trigger works for every company connected through that app.

1. Add any QuickBooks webhook trigger to a workflow and copy the Event delivery URL from its panel. Every QuickBooks trigger in your workspace shares this URL.
2. In the Intuit Developer portal, open your app, select Webhooks, then Production. Intuit keeps separate webhook settings for production and development, and TaskJuice connects to production companies.
3. Paste the URL as the Endpoint URL, open Show webhooks, tick the entities and operations you want events for (for example Invoice, Customer, and Payment), and save. Intuit can take up to five minutes to send the first event.
4. Copy the app's Verifier Token and save it on your QuickBooks OAuth client in TaskJuice, under Settings → Integrations → OAuth clients. TaskJuice uses it to check the intuit-signature header on every delivery and rejects anything unsigned.

One Intuit app delivers events for every company connected through it. To make a trigger fire for one client only, set its Company ID. A QuickBooks admin can find it under Settings → Account and settings → Billing & Subscription. Leave the field empty to fire for every connected company.

QuickBooks events name the changed record by ID only (intuitentityid). Add the matching Get action, such as Get Invoice, to read the record.

Triggers

Each core record type has its own trigger per change:

• New fires when a record is created. It covers accounts, bills, bill payments, credit memos, customers, deposits, employees, estimates, expenses, invoices, journal entries, payments, products, purchase orders, refund receipts, sales receipts, time entries, transfers, vendors, and vendor credits.
• Updated fires when one of those records changes. For customers, vendors, employees, products, and accounts it also fires when another record is merged into it; the merged-away ID arrives as data.deletedid.
• Deleted fires when one of those records is deleted. The record can no longer be read.
• Voided fires for bill payments, credit memos, expenses, invoices, payments, refund receipts, sales receipts, and transfers.
• Emailed fires when QuickBooks emails a credit memo, estimate, invoice, payment, purchase order, refund receipt, or sales receipt.

Settings and reference lists have one Changed trigger each, covering every operation: budget, class, currency, department, journal code, payment method, preferences, tax agency, and term. Branch on the event type to tell the operations apart.

Two invoice triggers poll, because QuickBooks sends no event for them. Both need their Company ID set and fire only for invoices that change state after you publish:

• Invoice Paid fires when an invoice's open balance reaches zero. It checks every 15 minutes by default. For an instant alternative, use New Payment and read the invoice from the payment line.
• Invoice Overdue fires when an unpaid invoice passes its due date. It checks hourly by default.

Actions

The integration covers the QuickBooks Online accounting surface across every major record type. Highlights:

• Create, get, update, query, and delete for invoices, estimates, sales receipts, credit memos, refund receipts, payments, bills, bill payments, expenses, purchase orders, vendor credits, deposits, transfers, journal entries, and time entries.
• Send and Download PDF for invoices, estimates, sales receipts, credit memos, refund receipts, payments, and purchase orders.
• Void for invoices, payments, sales receipts, and bill payments. Intuit's API offers no void for credit memos or refund receipts.
• Customer, vendor, employee, product, account, and class management.
• Find actions that look records up without writing a query: customers by email or name, products by SKU or name, vendors, employees, and accounts by name, classes and locations by full name (Parent:Child for a sub-class), and invoices, estimates, bills, purchase orders, sales receipts, and credit memos by document number. Matches come back in QueryResponse.<Entity>.
• Attach File uploads a file and attaches it to a record. Attach Note to Record adds a text note.
• Create Credit Card Payment records a payment from a home-currency bank account to a home-currency credit card account.
• Delete Transfer and Delete Attachable take the whole record from the matching Get action, because Intuit requires the full record to delete these.
• Run Report returns QuickBooks reports such as Profit and Loss. Get Changed Records returns everything that changed since a point in time.

Known limitations

• Intuit documents a production accounting API limit of 500 requests per minute per company and 10 concurrent requests per company. TaskJuice surfaces 429 responses as retryable rate-limit errors and honors any Retry-After hint.
• Every update needs the record's current SyncToken: fetch the record first. For customers, deposits, estimates, invoices, journal entries, payments, refund receipts, sales receipts, and transfers, TaskJuice sends a sparse update, so only the fields you fill in change. For accounts, bills, bill payments, classes, credit memos, employees, items, purchases, purchase orders, time activities, vendors, and vendor credits, QuickBooks supports only a full update, which clears every writable field you leave empty, including fields the action does not show. On a payment, a Line list you send replaces all of the payment's lines, even on a sparse update.
• Webhook delivery is at-least-once. TaskJuice drops a redelivered event with the same event id, but design downstream steps to be safe to repeat.
• Intuit expects a response within 3 seconds and retries a failed delivery at increasing intervals, up to every 6 hours. It also says events can arrive out of order, so use the event time, not arrival order.
• Intuit's webhooks don't cover every record type. For anything outside the trigger list, or to catch a missed event, use Get Changed Records, which is what Intuit recommends.
• The integration uses the production endpoint (quickbooks.api.intuit.com). Intuit sandbox companies and QuickBooks Desktop aren't supported.