QuickBooks Integration

The QuickBooks integration connects Kestrio to QuickBooks Online so your books reflect the invoices and credit notes you issue, and Kestrio reflects the payments your finance team records in QuickBooks.

Kestrio stays the system of record for delivery, time, approvals, and invoicing. QuickBooks receives the financial documents and sends back payments.

Integrations are available on Pro plans and above. Only users with the QuickBooks manage permission (Admins by default) can connect, configure, or disconnect it.

Navigation

Open Settings > Integrations > QuickBooks, or go to /settings/integrations/quickbooks.

The page has three tabs:

Tab	Use it for
Customer Mapping	Link each Kestrio account to a QuickBooks customer.
Item & Tax Mapping	Choose which QuickBooks item and tax code each kind of invoice line uses.
Sync Log	See every sync attempt, its direction, and its result.

What Syncs

Data	Direction	Notes
Invoices	Kestrio to QuickBooks	Sent when an invoice becomes approved or later. Voided invoices are voided in QuickBooks.
Invoice lines	Kestrio to QuickBooks	Sent with the invoice.
Payments recorded in Kestrio	Kestrio to QuickBooks	Created in QuickBooks against the synced invoice.
Payments recorded in QuickBooks	QuickBooks to Kestrio	Applied to the matching Kestrio invoice.
Credit notes	Kestrio to QuickBooks	Sent as QuickBooks credit memos.
Credit memos created in QuickBooks	QuickBooks to Kestrio	Only when linked to an invoice that came from Kestrio.
Customers	Mapping only	Kestrio does not create or edit QuickBooks customers.
Items and tax codes	Mapping only	Kestrio does not create QuickBooks items or tax codes.

Expenses, bills, and vendors are not synced to QuickBooks.

Which Invoices Sync

An invoice is sent to QuickBooks when it enters one of these statuses: Approved, Sent, Partially paid, Paid, Written off, or Overdue.

Draft and In review invoices are never sent. Moving an invoice to Voided voids it in QuickBooks if it had been synced earlier, and is skipped if it never was.

Editing an invoice that is already approved does not send the change automatically. Use Full Sync to push it.

Which Credit Notes Sync

Credit notes sync when they are Approved, Issued, or Applied, and again whenever they change in those statuses. Draft, pending approval, rejected, and void credit notes are not sent.

Voiding a credit note in Kestrio does not void the credit memo in QuickBooks. Void it in QuickBooks as well.

When a credit note is applied to invoices that are already in QuickBooks, Kestrio also creates a QuickBooks payment that links the credit memo to each invoice.

Payments Coming Back from QuickBooks

Payments created in QuickBooks are applied to Kestrio invoices that are linked to the payment.

• Each payment is recorded in Kestrio with method Other and the QuickBooks payment ID as the reference.
• Invoice balances and status update automatically. An invoice becomes Paid when nothing is left due, or Partially paid when some has been paid.
• Payments that link only to invoices Kestrio does not know about are skipped.
• Later edits or deletions of that payment in QuickBooks are not reflected.

Inbound payments arrive within moments if the QuickBooks webhook is set up for your deployment. Otherwise Kestrio checks QuickBooks for changes every 20 minutes.

Credit Memos Coming Back from QuickBooks

A credit memo created in QuickBooks is imported only if it is linked to an invoice that exists in Kestrio. It appears as an Applied credit note with the reason "Imported from QuickBooks" and a single line.

Connect QuickBooks

1. Open Settings > Integrations > QuickBooks.
2. Select Connect QuickBooks.
3. Sign in to Intuit and choose the QuickBooks company to connect.
4. Approve access. You return to Kestrio with a "QuickBooks connected successfully" message.

The connect link is valid for 10 minutes and must be completed in the same browser where you started it. If you cancel or the link expires, you see an error and can start again.

Once connected, the page shows the company name, its realm ID, the number of errors in the last 7 days, and the time of the last successful check for payments.

Whether Kestrio talks to the QuickBooks sandbox or production is a setting of your Kestrio deployment, not something you choose on this page. Confirm which one is configured before connecting a live company.

Set Up Mappings

Invoices will fail until the mappings below are in place. Complete them before you approve invoices you expect to sync.

Customer Mapping

Every account you invoice must map to an existing QuickBooks customer.

1. Open the Customer Mapping tab.
2. Select Match by Name. Kestrio links accounts whose name exactly matches a QuickBooks customer display name, ignoring case and extra spaces.
3. For accounts that remain unmapped, paste the QuickBooks customer ID in the row and select Save.

Things to know:

• Accounts that are already mapped are never overwritten by Match by Name.
• Kestrio does not check that a pasted ID exists in QuickBooks, so double-check it.
• Once an account is mapped, the page shows the ID read-only. There is no way to change or remove it from the page.
• Create any missing customers in QuickBooks first.

Item & Tax Mapping

QuickBooks invoice lines need an item. Choose one for each kind of Kestrio invoice line:

Line source	Used for
Time	Billable time.
Expense	Billable expenses.
Milestone	Milestone billing.
Fixed fee	Fixed fee billing.
Retainer	Retainer billing.
Manual	Lines typed in by hand. Also used for credit note lines that were not copied from an invoice.
Subscription fee	Subscription fees.
Support overage	Support overage charges.

Every line type that appears on an invoice or credit note must be mapped, or that document fails to sync with the message No QuickBooks item mapping configured for source type "...". Map Manual at minimum.

For tax, map each active Kestrio tax code that you use on invoice lines to a QuickBooks tax code. Only system tax codes such as TAX and NON are offered.

• A line whose tax code has no mapping is sent without a tax code. No error is shown.
• QuickBooks may calculate tax itself, so tax totals can differ between Kestrio and QuickBooks. Compare totals the first time you sync a taxed invoice.

Select Save Mapping to store both sections. You can change a mapping but not clear it from the page.

Common Workflows

Run the First Sync

1. Connect QuickBooks.
2. Create missing customers in QuickBooks.
3. Run Match by Name and map any leftovers.
4. Map items and tax codes.
5. Select Full Sync.
6. Open the Sync Log and confirm results.

Full Sync

Full Sync does four things:

1. Matches customers by name.
2. Sends every invoice in a syncable status.
3. Sends every approved, issued, or applied credit note.
4. Pulls all payments and credit memos from QuickBooks.

It returns quickly and keeps working in the background, and the page shows "Sync in progress...". Because it resends everything, it is also the way to retry failures and to push edits made to an already-approved invoice. Resending updates the QuickBooks document, so any manual edits to invoice lines made in QuickBooks are overwritten.

There is no retry button for a single record.

Fix a Failed Sync

1. Open the Sync Log and find the failed row.
2. Read the message and fix the cause. Common causes are in the table below.
3. Select Full Sync.

Failed jobs are tried three times, a few seconds apart, and then stop. They are not retried automatically later, so fix the cause and run Full Sync.

Message	Cause and fix
Account ... has no QuickBooks customer mapping	Map the account on the Customer Mapping tab.
No QuickBooks item mapping configured for source type ...	Map that line type on the Item & Tax Mapping tab.
Invoice ... has no line items	Add at least one line to the invoice.
Invoice ... has no QuickBooks mapping, it must sync before its payments can	The invoice never synced. Fix the invoice sync, then run Full Sync.
QuickBooks access has been revoked. Please reconnect.	Disconnect and connect again.
QuickBooks API error ...	QuickBooks rejected the document. The message includes QuickBooks' own explanation.

Review the Sync Log

The Sync Log lists attempts newest first, 20 per page. Each row shows start time, direction, entity, operation, status, and message.

Status	Meaning
In progress	The attempt is running.
Completed	The attempt finished. Check the message, because skipped items also show Completed.
Failed	The attempt failed.

A message that starts with "Skipped" means nothing was sent on purpose, for example a status that does not sync. The error count in the page header counts failed attempts, so one invoice that fails three times counts as three.

Disconnect QuickBooks

Select Disconnect on the QuickBooks page. Kestrio revokes its access in QuickBooks, removes the connection, and cancels waiting jobs. There is no confirmation prompt.

Customer mappings, item and tax mappings, and sync history are kept. If you reconnect to the same company they are reused. If you connect a different QuickBooks company, review every mapping first, because the saved IDs belong to the old company.

Good to Know

• Kestrio wins. Invoice edits flow one way, from Kestrio to QuickBooks. Changes to invoices, customers, or items made in QuickBooks are not pulled in.
• Payments are one-way per payment. Editing or voiding a payment after it has synced is not reflected in the other system. Fix it in both places.
• Order matters. A payment or credit application can only sync after its invoice has synced.
• Currency. Kestrio sends the invoice currency. If you invoice in a currency other than your QuickBooks home currency, make sure multicurrency is turned on in QuickBooks and test one invoice first.
• Duplicate numbers. Kestrio sends the Kestrio invoice number as the QuickBooks document number. If QuickBooks already has an unlinked invoice with that number, QuickBooks may reject or duplicate it.
• Plan changes. Syncing keeps running for a connected company even if the plan is later downgraded, but the page is locked.
• One QuickBooks company per connection. If two admins both connect in the same organization, the result is unpredictable. Have one admin connect and disconnect.
• "Active" does not mean healthy. The status badge does not change if QuickBooks access is revoked. Watch the Sync Log for "access has been revoked" and reconnect.
• Last synced shows the last successful check for payments from QuickBooks, not the last invoice sent.

Safety Notes

• Connect the correct QuickBooks company. Check the company name on the page after connecting.
• Test with the sandbox or a copy of your books before connecting live data.
• Map items and tax codes before approving invoices.
• Run Full Sync deliberately. It resends all syncable invoices and overwrites matching QuickBooks documents.
• Fix the underlying problem before retrying a failed sync.

Related Docs

• Integrations
• Invoices
• Credit Notes
• Financial Configuration
• Users, Roles, and Teams
• Troubleshooting