Documentation

Last updated: 24 August 2026

QuickBooks Timesheet Sync turns Jira and Tempo worklogs into QuickBooks Online time activities — on the right customer, project and employee, with the billable flag carried over. It then reads back which of those hours QuickBooks has invoiced, so nobody edits time that has already been billed. It does not create invoices, and it never writes to Jira.

Before you start

• Jira: you need to be a Jira administrator to install and configure the app.
• QuickBooks Online: a company on Plus or Advanced — the plans that include time tracking. The app checks this on connect and tells you if the company can't accept time activities.
• Tempo (optional): a Tempo API token, if you want Tempo worklogs and their billable split instead of native Jira worklogs.

Setup

1. Connect QuickBooks. Open Apps → QuickBooks Timesheets in Jira and click Connect QuickBooks. Sign in as an administrator of the QuickBooks company. Whoever connects becomes the identity the sync uses to read Jira worklogs, so use an account that can see every project you want synced.
2. Pick a default service item on the Setup tab. QuickBooks requires a service item on every time activity, so the app will not push anything until one is chosen.
3. Map your people and customers. On People, match each Jira user to a QuickBooks employee. On Customers, match each Jira project to a QuickBooks customer or sub-customer project. Time logged by someone unmapped, or on a project with no customer, is held back rather than guessed.
4. Turn syncing on in Setup. Until you do, the app still collects worklogs so you can preview exactly what would be pushed — but nothing reaches QuickBooks.

How the sync runs

• The pipeline runs every five minutes: collect new and changed worklogs, then push the eligible ones. Installations with no worklog activity for a week are throttled to hourly.
• Sync now on the dashboard runs the same pipeline immediately.
• Once a night the app reconciles: it re-checks billed status, re-reads the last 48 hours of worklogs in case anything was missed, and picks up Tempo deletions.
• Each worklog is tracked by its own id and a content hash, so re-running the pipeline can never create the same time activity twice.

Worklog statuses

Every worklog the app has seen carries one status, shown on the dashboard and the issue panel.

• Synced — a matching time activity exists in QuickBooks and is up to date.
• Billed — QuickBooks has invoiced those hours. See below.
• Waiting — eligible, queued for the next push.
• Held back — needs a person: an unmapped employee or customer, no default service item, or an unapproved Tempo period. Re-checked on every run, so fixing the mapping is enough to release it.
• Conflict — the worklog changed in Jira after QuickBooks had already billed it. The app refuses to overwrite billed time and asks you to decide.
• Error — the push was attempted and QuickBooks rejected it. The reason is shown on the row.

Billed time

When time is added to an invoice in QuickBooks, the app latches that hour as billed — within seconds via a QuickBooks webhook, and as a guarantee on the nightly reconcile. Billed hours show as billed on the Jira issue panel, so the person who logged the time can see it is already invoiced. If such a worklog is later edited in Jira, the app moves it to Conflict rather than rewriting the invoiced record.

Settings reference

• Time source — native Jira worklogs or Tempo. Switching source retires the old source's rows instead of deleting them, so the same hour is never pushed twice under a new id.
• Tempo: approved only — push only time in approved Tempo periods. On by default, because billed time cannot be un-billed in QuickBooks.
• Billable rule (native Jira only, which has no per-worklog billable flag) — treat everything as billable, nothing as billable, or decide by an issue label or by project.
• Rate source — let the QuickBooks service item price resolve the rate (the default, and what most teams want), or write the rate from the QuickBooks customer record.
• Sync from date — the earliest worklog date to push, so a first install doesn't back-fill years of history into a live ledger.

Troubleshooting

There are no employees to map

The app maps Jira users to QuickBooks employee records, and in some QuickBooks regions the Employees screen is only reachable through a payroll subscription. You do not need payroll to add an employee for time tracking. In QuickBooks choose + New → Single time activity, open the Name dropdown and click + Add new — that opens a plain employee form. Add your people there, then reload the People tab.

"This QuickBooks company doesn't expose time tracking"

Time activities require QuickBooks Online Plus or Advanced. On Simple Start or Essentials there is nothing for the app to write to. Upgrading the company and reconnecting resolves it.

Nothing is reaching QuickBooks

Check, in this order: syncing is turned on in Setup; a default service item is chosen; the people and customers involved are mapped; and the worklog date is on or after your sync-from date. The dashboard's Held back count and Needs attention list name the exact reason for each worklog.

The app asks you to reconnect

QuickBooks connections expire if unused for an extended period. The app refreshes the connection automatically well before that point, but an installation that has been idle for a long time needs an administrator to click Connect QuickBooks once more. Nothing already synced is affected.

What the app never does

• Write anything to Jira — Jira access is read-only.
• Create or send invoices.
• Touch banking, payroll, or anything in QuickBooks outside time activities.
• Overwrite time QuickBooks has already billed.
• Push anything at all before an administrator turns syncing on.

Support

Questions, bugs and feature requests go to the Crosstown Tech support portal. Please include your Jira site URL. See also Privacy & security for exactly what the app reads, writes and stores.