QuickBooks Online Integration

What Is This Integration?

The QuickBooks Online integration keeps your Taskip invoices, contacts, and payments in sync with your QuickBooks accounting software — automatically.

When you send an invoice in Taskip, it appears in QuickBooks. When a client pays that invoice in QuickBooks, Taskip marks it as paid. When you add a new contact, they’re created in QuickBooks too. No double-entry. No copy-pasting. No missed payments.

What syncs:

• Contacts — Taskip contacts → QuickBooks customers
• Invoices — Taskip invoices → QuickBooks invoices (as accounts receivable)
• Payments — two-way: Taskip-recorded payments push to QuickBooks, and QuickBooks-recorded payments pull back to Taskip every 10 minutes
• Credit Memos — Taskip credit memos → QuickBooks credit memos
• Refunds — Taskip refunds → QuickBooks refund receipts

What does NOT sync automatically:

• Draft invoices (only “Sent” invoices trigger sync)
• Invoices older than your connection date (use Manual Sync to push historical data)
• Multiple QuickBooks companies — one workspace connects to one QuickBooks company only

---

Before You Start

You will need:

• A QuickBooks Online account (sandbox or production) with at least one active company
• Administrator or Manager role in Taskip (other roles cannot access integrations)
• At least one Item created in QuickBooks (e.g. “Professional Services”) — every invoice line in QuickBooks must reference an Item
• A bank or clearing account in QuickBooks to receive payments

No API keys needed — QuickBooks uses a secure login flow (OAuth 2.0). You’ll simply log in to QuickBooks in your browser and approve the connection.

Sandbox users: If you’re testing in sandbox mode, make sure you have a sandbox company created in your Intuit Developer account under Dashboard → Sandbox → Companies. Without a sandbox company the connection will fail with “no sandbox companies found”.

---

Step-by-Step: Connect Your QuickBooks Account

Step 1 — Start the Connection

In Taskip, go to: Settings → Integrations → QuickBooks

Click Connect to QuickBooks.

Taskip generates a secure link and redirects you to the Intuit login page.

---

Step 2 — Log In to Intuit and Approve Access

You’ll land on Intuit’s own website. Log in with your Intuit credentials and click Connect.

QuickBooks will ask permission for:

• Reading and writing your contacts (customers)
• Reading and writing your invoices and payments
• Reading your account settings (for tax codes, items, and chart of accounts)
• Basic profile information (OpenID)

Click Connect to continue.

Important: Taskip only uses this access to sync your business data. Your Intuit credentials are never stored in Taskip — only a secure access token is saved (encrypted).

---

Step 3 — Pick Your QuickBooks Company

After approving access, Intuit asks you to select which QuickBooks company (called a “realm”) to connect. If you only have one company, it is selected automatically.

Select the company you want to connect to Taskip.

---

Step 4 — Confirm the Connection

You’ll be returned to Taskip with a green “Connected” status showing your QuickBooks company name.

From this moment:

• New contacts created in Taskip are pushed to QuickBooks automatically
• Invoices sent from Taskip are pushed to QuickBooks automatically
• Payments are synced in both directions

---

Disconnect QuickBooks

To remove the connection: Settings → Integrations → QuickBooks → Disconnect

This revokes Taskip’s access from QuickBooks immediately. Existing data in QuickBooks is not deleted — only the live sync stops. Your sync history in Taskip is also preserved.

---

Configure Your Settings

After connecting, go to the Settings tab to configure how data syncs.

Before configuring: Taskip fetches your live Items, Tax Codes, and Accounts directly from your QuickBooks company. These dropdowns will only populate after you are connected.

Required before first sync: At minimum you must set a Default Item and a Default Deposit Account before any invoices or payments will sync successfully.

---

Invoice Number Strategy

What it does: Controls what invoice number appears on the QuickBooks invoice.

Options:

Option	What it means
taskip (recommended)	Taskip’s own invoice number (e.g. INV-00042) is sent to QuickBooks as the document number. Both apps show the same number.
qbo	Taskip sends no number. QuickBooks auto-assigns its own sequential number. The two apps will show different numbers.

When to use taskip: When Taskip is your primary system and you want to reference the same invoice number in both places — for example when talking to a client or reconciling records.

When to use qbo: When QuickBooks is the numbering authority, or when you already have invoices in QuickBooks and want to avoid number conflicts.

Example: Your Taskip invoice is INV-00042. With strategy taskip, QuickBooks also shows INV-00042. With strategy qbo, QuickBooks generates its own number like 1003 — the same invoice, two different numbers.

---

Default Item (Required for invoice sync)

What it does: Every line on a QuickBooks invoice must be linked to an Item from your QuickBooks Items list. This setting is the fallback Item used when a Taskip invoice line has no specific category mapping.

Why you’d set it: Without this, invoice sync will fail for any line that doesn’t match an item_mappings entry. This is the most common reason invoice sync fails.

How to set it: Click “Load Items” to fetch your QuickBooks Service items, then select your general-purpose item — for example “Professional Services” or “General Work”.

Example: You have a QuickBooks Item called “Consulting Services” with ID 7. Set this as the Default Item. Now any Taskip invoice line without a specific category mapping will be sent to QuickBooks under “Consulting Services”.

---

Default Tax Code

What it does: When an invoice line doesn’t have a specific tax mapping, Taskip uses this tax code as the fallback on that line in QuickBooks.

How to set it: Click “Load Tax Codes” to fetch your QuickBooks tax codes, then select your standard rate. Common values are TAX (taxable) or NON (non-taxable).

Example: Most of your services are non-taxable. Set NON as the default. If a specific line item has a tax rate in Taskip, you can map that separately using Tax Mappings.

---

Default Deposit Account (Required for payment sync)

What it does: When a payment is recorded, Taskip pushes it to QuickBooks and deposits it into this account.

Why you’d set it: QuickBooks requires a deposit account on every payment. Without this setting, payment sync is silently skipped — QuickBooks invoices will remain unpaid even when Taskip marks them as paid.

How to set it: Click “Load Accounts” to fetch your active QuickBooks accounts, then select your main bank or clearing account (e.g. “Business Checking” or “Undeposited Funds”).

Example: You receive client payments into your “Business Checking” account in QuickBooks. Select that account here. Every payment pushed from Taskip will land in that account.

---

A/R Account (Accounts Receivable)

What it does: Specifies which Accounts Receivable account to use when creating invoices in QuickBooks.

When to set it: Only if your QuickBooks company has multiple A/R accounts (uncommon). Most businesses have one A/R account and can leave this blank — QuickBooks uses its default automatically.

Example: A large firm has separate A/R for domestic clients and international clients. They’d set the correct A/R account here so Taskip invoices land in the right ledger.

---

Tax Mappings

What it does: Maps each Taskip tax rate to a specific QuickBooks tax code, overriding the Default Tax Code for that particular rate.

Why you’d set it: If you use multiple tax rates in Taskip (e.g. standard rate and zero rate), this ensures each one appears with the correct QuickBooks tax code — not just the default.

Format: A JSON object where keys are Taskip tax IDs and values are QuickBooks tax code IDs.

Example:

Taskip Tax	QuickBooks Tax Code
Standard 10% GST (ID: 1)	TAX
Zero Rated (ID: 2)	NON

{ "1": "TAX", "2": "NON" }

Any line with Taskip tax ID 1 sends TAX to QuickBooks. Any line with ID 2 sends NON. Lines with no match fall back to the Default Tax Code.

---

Item Mappings

What it does: Maps Taskip invoice line categories to specific QuickBooks Items, overriding the Default Item for that category.

Why you’d set it: If you bill for different types of work and want each category to appear under the correct QuickBooks Item — for cleaner reporting and revenue breakdown in QuickBooks.

Format: A JSON object where keys are Taskip category slugs and values are QuickBooks Item IDs.

Example:

Taskip Category	QuickBooks Item
Design	“Design Services” (Item ID: 21)
Development	“Development Work” (Item ID: 34)
Consulting	Default Item (no mapping needed)

{ "design": "21", "development": "34" }

Lines categorised as “design” in Taskip go to Item 21 in QuickBooks. “development” lines go to Item 34. All other lines fall back to the Default Item.

---

API Minor Version

What it does: Pins the QuickBooks API version used for all requests. Default is 70.

When to change it: Only if Intuit support instructs you to. Leave this as 70 in all normal circumstances.

---

What Syncs Automatically

Once connected and configured, this all happens without you doing anything:

Action in Taskip	What happens in QuickBooks
New contact created	Customer created in QuickBooks
Contact name, email, or phone updated	QuickBooks customer updated
Invoice status changes to Sent	Invoice created in QuickBooks (accounts receivable)
Sent invoice edited	QuickBooks invoice updated (if not yet paid)
Invoice voided	QuickBooks invoice voided
Payment recorded in Taskip	Payment pushed to QuickBooks against the correct invoice
Invoice fully paid in QuickBooks	Taskip invoice automatically marked as paid (checked every 10 min)
Credit memo issued in Taskip	Credit memo created in QuickBooks
Refund issued in Taskip	Refund receipt created in QuickBooks

Important — sync contacts before invoices: When you sync invoices, Taskip needs the matching contact to already exist in QuickBooks. Taskip will attempt to auto-push the contact if it is missing, but if the contact push fails (for example, because a customer with the same name already exists in QuickBooks), the invoice will also fail. Always run Sync Contacts first, then Sync Invoices. See the Manual Sync section below.

---

How the Sync Works — Inside Detail

Contacts

When you create or update a contact in Taskip, a background job (QboContactSyncJob) runs immediately.

What gets sent to QuickBooks:

• Display name
• Email address
• Phone number
• Billing address
• Currency

Update logic: QuickBooks uses a version number called a SyncToken on every record. Taskip stores this token after every sync. When updating a contact, Taskip sends the stored SyncToken to QuickBooks to confirm the record hasn’t changed on the QuickBooks side. If the token is stale (someone edited the customer directly in QuickBooks), the update is safely rejected and logged — no data is corrupted.

---

Invoices

Invoices sync when their status changes — not when they’re created as drafts.

Trigger: Invoice → Sent Taskip dispatches QboInvoiceSyncJob with action create. The invoice is created in QuickBooks.

Trigger: Sent invoice edited Taskip dispatches QboInvoiceSyncJob with action update. Before updating, Taskip re-reads the current SyncToken from QuickBooks to avoid version conflicts.

Trigger: Invoice voided Taskip dispatches QboVoidInvoiceJob. The invoice is voided in QuickBooks (not deleted — voided preserves the audit trail).

What gets sent to QuickBooks:

• Invoice number (based on your chosen strategy: taskip or qbo)
• Due date
• Customer reference (auto-pushed if the contact isn’t in QuickBooks yet)
• Line items — each with:
  • Item reference (from item_mappings or default_item_id)
  • Tax code (from tax_mappings or default_tax_code_id)
  • Description, quantity, unit price
• Currency
• Internal memo (PrivateNote)
• Customer-facing memo (CustomerMemo)

---

Payments

Taskip → QuickBooks: When a payment is recorded in Taskip against a sent invoice, QboPaymentSyncJob runs immediately. It creates a Payment in QuickBooks, linked to the correct QuickBooks invoice, deposited into your configured deposit account.

QuickBooks → Taskip (reverse sync): Every 10 minutes, Taskip checks QuickBooks for invoices where the outstanding balance has reached zero (fully paid). If found in the sync records, Taskip automatically marks the matching Taskip invoice as paid. This covers cases where your accountant records a payment directly inside QuickBooks.

Requirement: The Default Deposit Account must be configured or payment sync is silently skipped in both directions.

---

Credit Memos & Refunds

These push from Taskip to QuickBooks only (no reverse sync):

• Credit memo in Taskip → QboCreditMemoSyncService → QuickBooks CreditMemo, linked to the customer
• Refund in Taskip → QboCreditMemoSyncService → QuickBooks RefundReceipt

---

Two-Way Payment Sync

Payments are the only entity that syncs in both directions:

Taskip → QuickBooks: When you record a payment in Taskip, it pushes to QuickBooks and applies against the invoice in the deposit account you configured.

QuickBooks → Taskip: Taskip polls every 10 minutes per workspace for QuickBooks invoices with a zero balance. When found and matched, Taskip updates the invoice status to paid automatically.

This means your books stay in sync regardless of which side the payment is recorded on.

---

Manual Sync

If you’ve just connected and want to push existing data across, use the manual sync options:

Step 1 — Sync All Contacts (do this first) Go to Settings → Integrations → QuickBooks → Sync and click Sync Contacts. Pushes all Taskip contacts to QuickBooks as Customers. Runs in the background — typically completes within a few minutes.

Why contacts must go first: Every QuickBooks invoice must be linked to a Customer. When Taskip syncs an invoice, it looks up the matching Customer ID from the contacts it already pushed. If the contact hasn’t been synced yet, the invoice sync fails with an error. There is no way to create an invoice in QuickBooks without a customer — sync contacts first, every time.

Step 2 — Sync All Invoices (only after contacts finish) Click Sync Invoices. Pushes all Taskip invoices with Sent status or later to QuickBooks. Runs in the background.

Wait for contact sync to finish before starting invoice sync. If contact sync is still running in the background, invoice sync will fail for any invoice whose contact has not been pushed yet. Check Sync Health — when all contacts show green, invoice sync is safe to start.

API endpoints (for developers):

POST /api/v3/integrations/quickbooks/sync/contacts
POST /api/v3/integrations/quickbooks/sync/invoices

---

Sync Health: Monitoring Your Sync

Go to Settings → Integrations → QuickBooks → Sync Health to see a log of every sync action.

What you’ll see:

Column	What it means
Entity	Contact, invoice, payment, credit memo, or refund
Action	create, update, void, sync_payment, pull_payment, credit_memo, or refund
Direction	Push (Taskip → QuickBooks) or Pull (QuickBooks → Taskip)
Status	Green = success, Red = failed
Retries	How many times it has been attempted (max 5)
Error	The error message from QuickBooks if it failed
Date	When it was last attempted

Failed syncs: Most sync jobs automatically retry 3 times with a 60-second delay between attempts. You can also click Retry on any failed row to re-queue it immediately.

API endpoint (for developers):

GET  /api/v3/integrations/quickbooks/sync-logs
POST /api/v3/integrations/quickbooks/sync-logs/{id}/retry

---

Quick Troubleshooting

“There is no sandbox companies found for the user” (during connect)

• You are connecting in sandbox mode but your Intuit developer account has no sandbox companies
• Go to developer.intuit.com → Dashboard → Sandbox → Companies → Add sandbox company
• Try connecting again

“Missing realmId from QuickBooks” error

• This is a frontend configuration issue — the frontend page at /quickbooks-oauth-redirect was not forwarding the realmId parameter (camelCase) in the POST body to the backend
• Confirm the frontend sends { code, state, realmId } — not realm_id

“My contact didn’t appear in QuickBooks”

• Check Sync Health for an error on that contact
• Make sure the contact has a Display Name — QuickBooks requires it
• Confirm the connection is still active (Settings → QuickBooks → Connection)

“My invoice wasn’t pushed to QuickBooks”

• Invoices are only synced when they reach Sent status — draft invoices are not pushed
• Check Sync Health for a failed invoice entry
• Verify your Default Item is set in Settings — this is the most common cause of invoice sync failure

“Payment sync isn’t working”

• Confirm a Default Deposit Account is selected in Settings — payments cannot push without one
• Check that the invoice was already synced to QuickBooks — a payment cannot be applied to an invoice that doesn’t exist in QuickBooks yet
• Check Sync Health for a failed payment entry

“Invoice number conflict in QuickBooks”

• Switch Invoice Number Strategy from taskip to qbo — QuickBooks will auto-assign its own numbers instead of using your Taskip invoice numbers
• This happens when QuickBooks already has an invoice with the same number

“I connected but nothing is syncing”

• Check the connection status — access tokens expire after 60 minutes and refresh automatically. If refresh fails, the connection status changes to error (status 2). Try disconnecting and reconnecting.
• Confirm your Default Item and Default Deposit Account are set

“Contact not yet synced to QBO — sync contacts first”

• An invoice sync was attempted but the contact linked to that invoice has not been pushed to QuickBooks yet
• Run Sync Contacts first, wait for it to complete, then run Sync Invoices again
• Also check Sync Health for the contact — if it failed for a different reason, fix that first

“The name supplied already exists” (contact sync error)

• QuickBooks requires every Customer to have a unique Display Name. A customer with the same name already exists in your QuickBooks company (likely added manually before you connected Taskip)
• Taskip automatically handles this by finding the existing QuickBooks customer with the same email and linking the contact to it — no duplicate is created
• If the contact still shows as failed, check that the contact’s email in Taskip matches the email on the existing customer in QuickBooks

“Invoice number is too long” / DocNumber rejected

• QuickBooks has a 21-character limit on invoice numbers. If your Taskip invoices use a long format (such as a full UUID like 550e8400-e29b-41d4-a716-446655440000), Taskip automatically truncates to 21 characters before sending to QuickBooks
• The full invoice number is still stored in the QuickBooks invoice’s private note field for reference
• If you see number mismatches in QuickBooks, this is expected — the truncated number is a display label only

“SyncToken conflict” in sync logs

• This means the record was modified directly in QuickBooks between Taskip syncs. Retry the sync — Taskip re-reads the latest SyncToken before the retry.

---

Summary Checklist

Get fully set up in under 10 minutes:

• Go to Settings → Integrations → QuickBooks and click Connect to QuickBooks
• Log in to Intuit and click Connect
• Select your QuickBooks company
• Confirm the green “Connected” status appears with your company name
• Go to Settings tab → load Items, Tax Codes, and Accounts
• Set your Default Item — required for invoice sync
• Set your Default Deposit Account — required for payment sync
• Set your Default Tax Code
• Set Invoice Number Strategy (taskip recommended)
• (Optional) Set up Tax Mappings for multi-rate tax setups
• (Optional) Set up Item Mappings for category-specific QuickBooks items
• Leave A/R Account blank unless you have multiple A/R accounts in QuickBooks
• Run Sync All Contacts to push existing contacts — wait for this to finish before the next step
• Check Sync Health — confirm all contacts are green before proceeding
• Run Sync All Invoices to push existing sent invoices
• Check Sync Health to confirm everything came through