For Jira Cloud + QuickBooks Online
Documentation
& setup guide.
Everything needed to install InvoiceBridge, connect a QuickBooks Online company, configure a Jira project, and turn tracked worklogs into unsent invoices — plus a step-by-step walkthrough for verifying every function of the app on a test site.
Contents
What InvoiceBridge is
InvoiceBridge reads the worklogs your team already logs in Jira and turns the ones you select into an unsent invoice in your own QuickBooks Online company. Every line is shown to you before anything is created, and nothing is ever emailed to a customer on your behalf.
It is built entirely on Atlassian Forge. There is no Worqflow server in the middle: your worklog data travels from Atlassian to exactly one destination — the QuickBooks company you connect.
How it works
| Read | For the project and date range you choose, InvoiceBridge finds issues with worklogs in that window, then reads those worklogs: issue key and summary, who logged the time, when, and how long. |
|---|---|
| Price | Each worklog is priced at the per-project rate, falling back to the site-wide default rate. Hours are rounded to two decimals and amounts are derived from those same rounded hours, so the figure on the invoice always equals QuickBooks' own quantity × unit price. |
| Preview | The priced rows are shown in a table — date, issue, person, hours, rate, amount — with every row selected by default. You uncheck anything you don't want to bill. |
| Create | The selected rows become an invoice in QuickBooks with EmailStatus: NotSet —
an unsent invoice. Tax, numbering, terms and the send button all stay in QuickBooks, and stay yours. |
| Record | Every invoiced worklog is written to a ledger held in Atlassian app storage. A worklog that has been invoiced once will never appear as billable again. |
Requirements
- Jira Cloud, with time tracking in use — InvoiceBridge bills from Jira worklogs.
- A QuickBooks Online company, and an Intuit login with access to it. A QuickBooks Online sandbox company works for evaluation and testing.
- In QuickBooks: at least one active customer and one active service item to bill against.
- Jira administrator rights to connect QuickBooks (the admin page), and project administrator rights on a project to configure and bill it.
Install & connect QuickBooks
Connecting is done once, by a Jira admin, from Jira Settings → Apps → InvoiceBridge. The page has three parts, in order.
-
Install the app
Install InvoiceBridge from the Atlassian Marketplace onto your Jira Cloud site. It adds one admin page and one project page; it does not modify issues, workflows or permissions.
-
Connect your Intuit login
On the admin page, under 1. Your Intuit login, click Connect Intuit login. Intuit's own sign-in and consent screen opens; approve access. The connection is per Atlassian user and is held by Atlassian's Forge external-authentication service — InvoiceBridge never sees or stores your Intuit password. The page then reads “✅ Your Atlassian user is connected to Intuit.”
-
Point it at your QuickBooks company
Under 2. QuickBooks company, paste your QuickBooks Company ID, choose the environment — Production for a real company, Sandbox for a developer test company — and click Validate & save. InvoiceBridge calls QuickBooks to confirm the ID resolves against your connection and echoes back the company name it found, so a mistyped ID cannot be saved silently.
-
Set site-wide defaults
Under 3. Defaults, set the default hourly rate used where a project has none, and choose how invoice lines are grouped: one line per worklog, or one line per issue (worklogs on the same issue at the same rate are merged into a single line). Click Save defaults.
Set up a Jira project
Each project you bill is configured once, by a project admin, from that project's QuickBooks Billing page in the project menu.
On first visit the page shows Set up this project, with customers and service items loaded live from the connected QuickBooks company:
- Customer — the QuickBooks customer this project's invoices are billed to.
- Service item — the QuickBooks service item every line is booked against.
- Rate $/h — this project's hourly rate. Left at zero, the site-wide default applies.
- Currency — must match the currency the QuickBooks customer bills in.
Click Save. The settings can be changed later with Edit settings.
Create an invoice
-
Choose the period
Set From and To, then click Refresh. The first time, the range defaults to the last 30 days; afterwards From defaults to where the previous invoice ended, so consecutive periods meet without a gap or an overlap.
-
Review the lines
Each uninvoiced worklog in the range appears as a row: date, issue, person, hours, rate, amount. Everything is selected by default — uncheck any row you don't want on this invoice. The running Total selected updates as you go.
-
Create the unsent invoice
Click Create unsent invoice — the button also shows how many worklogs are selected, e.g. Create unsent invoice (3 worklogs). InvoiceBridge re-reads the worklogs and recomputes every amount server-side — the figures posted to QuickBooks are never taken from the browser — then creates the invoice.
-
Review and send in QuickBooks
A confirmation shows the new invoice number and total, with an Open in QuickBooks link. The invoice is waiting there, unsent. Apply tax, adjust wording, and send it when you're ready.
What keeps the numbers honest
| No double billing | Every invoiced worklog is recorded in a ledger. Invoiced worklogs are filtered out of later previews, and an attempt to bill one anyway is refused with the offending worklog ids named. |
|---|---|
| Edits don't hide | If a worklog's time is changed after it was invoiced, the preview raises a drift warning naming the issue and both figures — invoiced 3.5h → now 4h — so you can decide what to do in QuickBooks. It is never silently re-billed. |
| Interrupted attempts | Invoice creation writes an intent record first and marks each invoice with a private-note marker. If a run is interrupted, the next attempt finds and adopts the invoice it already created instead of creating a second one. Anything still unresolved after an hour is surfaced as a warning to check QuickBooks before retrying. |
| Currency | If the project's configured currency doesn't match what the QuickBooks customer bills in, creation stops with an explicit message rather than posting a wrongly-denominated invoice. |
| Nothing is sent | Invoices are created with EmailStatus: NotSet. InvoiceBridge has no
code path that emails an invoice. |
| Permission checks | Before any privileged read or write, the app verifies the calling user's own Jira permission — project administrator for project billing actions, Jira administrator for the connection settings — and fails closed if that check cannot be completed. |
Verifying functionality — step by step
This walkthrough exercises every function of the app end to end on a test Jira site against a QuickBooks Online sandbox company. It takes about fifteen minutes.
The sandbox company provided for review already contains active customers and service items, so there is nothing to prepare on the QuickBooks side. If you use a sandbox of your own instead, add at least one active customer and one active service item first — the app bills against them.
jira-administrators group and from the project's administrator role for that
step, then restore it. Every other step needs only the admin account.
Prepare test data in Jira
-
Create a project and an issue
Create (or pick) a Jira project, and create an issue in it — for example
IBT-14 · Fix login bug. -
Log work on it
On the issue, use Log work to record time — for example
3h 30m, dated today. Log a second entry on another issue if you want to see multiple lines.
Connect QuickBooks
-
Open the admin page
As a Jira admin, go to Settings → Apps → InvoiceBridge.
The page loads with “Not connected yet.” -
Connect the Intuit login
Click Connect Intuit login and complete Intuit's sign-in and consent screen with the sandbox credentials.
The page returns to “✅ Your Atlassian user is connected to Intuit.” -
Validate the company
Paste the sandbox Company ID, set Environment to Sandbox, and click Validate & save.
A green confirmation naming the sandbox company, e.g. ✅ Connected to “Sandbox Company US 9b2f” — proof the app really reached QuickBooks. A deliberately wrong Company ID is rejected instead of saved. -
Save defaults
Set a default rate — say
The values persist across a page reload.120— leave grouping at One line per worklog, and click Save defaults.
Configure the project and bill it
-
Open the project's billing page
Go to the project and open QuickBooks Billing from the project menu.
A Set up this project panel, with the Customer and Service item dropdowns populated from the sandbox company — confirming live reads from QuickBooks. -
Configure it
Pick a customer and a service item, set the rate to
120, leave currencyUSD, and click Save. -
Preview the worklogs
Set From and To to cover the day you logged work, then click Refresh.
A row per logged worklog —3.5hours at$120.00/hfor$420.00— and a matching Total selected. -
Create the invoice
Leave the rows checked and click Create unsent invoice.
A green banner naming the new invoice number and total, with an Open in QuickBooks link. -
Verify it in QuickBooks
Follow that link into the sandbox company and open the invoice.
An invoice for the right customer and total, unsent, with one line per worklog described asIBT-14 Fix login bug — Ana, 3.5h × $120.00, and anInvoiceBridge marker: IB-…string in the private note.
Verify the safeguards
-
A worklog is billed once
Back in Jira, click Refresh on the billing page.
The worklogs you just invoiced are gone from the table — “No uninvoiced worklogs in this range.” They cannot be billed a second time. -
Edits to invoiced work are surfaced
In Jira, edit the worklog you already invoiced — change
An amber drift warning: 1 already-invoiced worklog(s) changed since invoicing: IBT-14 (3.5h → 4h). The row is not silently re-billed.3h 30mto4h— then Refresh. -
Line grouping
Log two worklogs on the same issue, switch the admin default to One line per issue, then preview and invoice them.
One merged invoice line carrying the summed hours, instead of two. -
Permissions are enforced
As a Jira user who is not a project admin, open the project's QuickBooks Billing page. As a user who is not a Jira admin, open the InvoiceBridge admin page.
Both refuse with a permission error rather than returning data. Billing actions require project administrator on that project; connection settings require Jira administrator. -
Nothing is emailed
Check the invoice's status in QuickBooks.
It remains unsent until a human sends it from QuickBooks.
Permissions, data & egress
Atlassian scopes
| read:jira-work | Find issues with worklogs in the chosen project and date range, and read those worklogs — issue key and summary, time logged, when, and by whom. Also backs the caller's own permission check before any privileged action. |
|---|---|
| read:jira-user | Resolve the display name of the person who logged the time, so an invoice line can say who did the work, and identify the admin who connected QuickBooks. |
| storage:app | Hold the app's own state: the QuickBooks connection and defaults, per-project billing settings, and the ledger of which worklogs have already been invoiced. |
What leaves Atlassian, and where it goes
InvoiceBridge sends data to Intuit only — to the QuickBooks Online company that your own administrator connected. There is no Worqflow-operated server, no analytics endpoint, and no other third party.
| appcenter.intuit.com | Intuit's OAuth authorization screen, where your admin signs in and grants access. Handled by Atlassian's Forge external-auth service. |
|---|---|
| oauth.platform.intuit.com | Token exchange and refresh. |
| accounts.platform.intuit.com | Reads the connected Intuit identity (the OpenID profile) so the connection can be attributed. |
| quickbooks.api.intuit.com sandbox-quickbooks.api.intuit.com | The QuickBooks Online accounting API — production and sandbox respectively. Reads company info and preferences, the active customer and service item lists, and — only when recovering an interrupted attempt — searches that customer's invoices in a narrow date window to find one it may already have created. Creates the invoice. |
The content of an invoice line is the data that reaches Intuit: issue key, issue summary, the display name of the person who logged the time, hours and rate. Nothing else from Jira is transmitted — no comments, no attachments, no other issue fields, and no data about issues without billed worklogs.
One piece of app-generated data is written alongside it: each invoice carries
InvoiceBridge marker: IB-… in its QuickBooks private note. The marker is a one-way hash of the
project key and the invoiced worklog ids — it identifies the invoice as one of ours on a later recovery attempt,
and carries no readable Jira content.
Data kept, and for how long
- App state lives in Atlassian's own storage for the installation: the connection settings, per-project billing configuration, and the invoiced-worklog ledger.
- The ledger is what makes double-billing impossible; it holds worklog ids, the invoice each belongs to, the amount and the hours as invoiced.
- Uninstalling the app removes this state along with the installation. Invoices already created stay in your QuickBooks company, where they belong.
- Intuit's own OAuth tokens are held by Atlassian's Forge external-auth service, not by the app.
See Privacy for the full statement.
Troubleshooting
| “QuickBooks is not configured” | No company has been connected yet, or the connection was made in a different environment. A Jira admin should complete the admin page. |
|---|---|
| Customer / service item dropdowns are empty | Your own Intuit login isn't connected yet, or the connected company has no active customers or service items. Connect on the admin page, and check the company in QuickBooks. |
| “Could not validate Company ID” | The Company ID doesn't match the connected Intuit account, or the environment is set to Production for a sandbox company (or the reverse). |
| Currency mismatch | The project's configured currency differs from the QuickBooks customer's currency. Change one so they agree. |
| “Refusing: … already invoiced” | Working as designed — those worklogs are already on an invoice. Refresh the preview to see what is genuinely outstanding. |
| An earlier attempt may not have completed | Check QuickBooks for an invoice matching the project before creating another, then retry — the retry adopts the existing invoice rather than duplicating it. |
| No rows in the preview | There are no uninvoiced worklogs in that range. Widen the dates, or confirm the work was logged on issues in this project. |
Support
Email briano@worqflow.org. Support hours are Monday–Friday, 9:00 AM–5:00 PM America/Chicago, with a target first response within one business day.
When reporting a problem, the project key, the date range, and the exact message shown on screen are usually enough to identify it.