FiscoBridge Help Main Site

Connecting QuickBooks

QuickBooks Online is connected through OAuth via Intuit — FiscoBridge never sees your QuickBooks password. Once connected, your QuickBooks invoices are automatically synced and fiscalized.

Before You Begin

You will need:

  • A QuickBooks Online account. QuickBooks Desktop is not supported — the integration uses Intuit's cloud REST API.
  • Admin access to the QuickBooks company you want to connect. Intuit's OAuth consent screen requires an admin to authorize third-party apps.
  • A FiscoBridge account with an active integration license and a valid PFX certificate.

Setting Up the Connection

  1. Go to Integrations → Integrations in the sidebar
  2. Click Create Integration

Integrations page with the Create Integration button highlighted

  1. On the New Integration page, select the QuickBooks card

New Integration page showing platform cards with the QuickBooks card highlighted

  1. Pick the tier and subscription to bill the connection against (if you have more than one)
  2. Upload your PFX certificate when prompted
  3. The QuickBooks confirmation dialog opens — review the certificate summary and click Connect

FiscoBridge QuickBooks dialog showing the Certificate Ready card and the Connect button

  1. You'll be redirected to Intuit's authorization page
  2. Sign in to your Intuit account (if not already signed in)
  3. Select the QuickBooks company you want to connect
  4. Click Connect (sometimes labelled Authorize)

Intuit authorization page asking to select a QuickBooks company and grant FiscoBridge access

  1. You'll be redirected back to the Customer Portal

Once authorized, the QuickBooks integration appears in your integrations list with status Active.

Right after you authorize, FiscoBridge also creates any tax codes your country's tax labels need that are missing from your QuickBooks company — existing tax codes are never changed. You still need to select these tax codes on your invoice lines; see Automatic setup when you connect.

Integrations list showing the QuickBooks integration with Active status badge

Multi-company: QuickBooks authorization is scoped to a single company ("realm") at a time. If you run several QuickBooks companies, create one FiscoBridge integration per company.

Fiscalization Trigger

When you connect QuickBooks, you decide at what point each invoice should be fiscalized. There are two options:

When payment is added (default)

The invoice is fiscalized once it's fully paid in QuickBooks (its balance reaches zero).

  • Best when you want the fiscal receipt to reflect the moment of payment
  • Unpaid invoices stay in QuickBooks without being sent to the tax authority
  • Partially paid invoices are not fiscalized until the balance reaches zero
  • An invoice created before you connected FiscoBridge is fiscalized when it's paid after connecting; one that was already fully paid before you connected is not fiscalized, even if you edit it later
  • The fiscal receipt shows how the invoice was paid, taken from the payment method on each QuickBooks payment — see Payment types

When invoice is created

The invoice is fiscalized as soon as it's saved in QuickBooks, whether or not it has been paid.

  • Best when you issue the fiscal receipt at the moment of sale
  • QuickBooks has no draft stage for invoices, so check the invoice before you save it
  • Invoices created before you connected FiscoBridge are not fiscalized, even if you edit them later

Note: To change the trigger, receipt format or training mode later, open the ⋮ menu on the QuickBooks integration and choose Settings — you don't need to reconnect. The new settings apply to invoices processed from then on.

What Gets Synced

  • Invoices from QuickBooks are pulled into FiscoBridge automatically when they reach your fiscalization trigger
  • Each sales-item line becomes an item on the fiscal invoice, preserving quantity and unit price
  • Invoices with amounts exclusive of tax, inclusive of tax or out of scope of tax are all supported — the fiscal receipt total always matches the QuickBooks invoice total, tax included
  • An invoice-level discount is spread across the invoice lines in proportion, so the fiscal receipt still matches the discounted total
  • Tax codes on QuickBooks invoice lines are mapped to the tax labels your tax authority recognises (see Tax Labels below) — an invoice with an unmapped tax code is not fiscalized until you fix the mapping
  • The buyer tax number is read from the QuickBooks customer record when available
  • Each invoice is fiscalized — signed and reported to the tax authority — only once. Changes made in QuickBooks after an invoice is fiscalized don't affect its fiscal receipt; raise a credit memo and a new invoice if the amount has to change
  • The fiscal receipt is attached to the QuickBooks invoice as a PDF (slip or A4, per your Receipt format), together with a note that records the fiscal invoice number and verification link. You'll find both under Attachments on the invoice
  • Credit memos and refund receipts are fiscalized as refunds of the original fiscal receipt — see Credit Memos and Refunds

QuickBooks notifies FiscoBridge when an invoice, credit memo or refund receipt is saved, so documents are usually fiscalized within a minute or two. FiscoBridge also checks QuickBooks every 5 minutes, so nothing is missed if a notification is delayed or doesn't arrive.

Payment types

Every fiscal receipt records how it was paid — Cash, Card, Check, Wire Transfer, Voucher, Mobile Money or Other. FiscoBridge takes this from the payment method you select when you receive a payment in QuickBooks:

QuickBooks payment method Fiscal payment type
Cash Cash
Credit Card, Debit Card, EFTPOS, Visa, MasterCard, Amex, Diners — or any method QuickBooks marks as a credit card Card
Cheque, Check Check
Bank Transfer, Direct Debit, Direct Deposit, EFT, Wire Wire Transfer
Voucher, Gift Card Voucher
M-PAiSA, MyCash, Mobile Money Mobile Money
Anything else, or no method selected Other

Matching ignores capitals, spaces and punctuation, so Bank transfer and BANK-TRANSFER both count as Wire Transfer.

  • If an invoice was paid in several payments, the receipt lists each payment type with its amount (for example 60.00 Cash and 40.00 Card)
  • Any part of the invoice settled by a credit memo rather than a payment is listed as Other
  • With the When invoice is created trigger, the invoice is fiscalized before any payment exists, so the payment type is always Other
  • Refund receipts use the payment method on the refund receipt; refunds from credit memos are recorded as Other
  • The payment type never stops an invoice from being fiscalized — an unknown method is simply reported as Other

Your customer receives the fiscal PDF

The fiscal receipt PDF is marked Attach to email, so when you email the invoice from QuickBooks your customer gets the fiscal receipt with it. Training receipts are never attached to emails — test receipts stay inside QuickBooks.

Credit Memos and Refunds

When you issue a credit memo or a refund receipt in QuickBooks, FiscoBridge fiscalizes it as a refund of the original fiscal receipt. The refund PDF and a note with the fiscal refund number and verification link are attached to the credit memo or refund receipt.

Credit memos and refund receipts are fiscalized as soon as they're saved, whichever fiscalization trigger you use — provided the original invoice has been fiscalized.

The tax authority requires every refund to reference the fiscal receipt it reverses, but QuickBooks doesn't store which invoice a credit memo belongs to. Add a custom field so you can record it:

  1. In QuickBooks, go to Settings ⚙ → Account and settings → Sales
  2. Under Custom fields, add a field named Original Invoice and make it available on sales forms
  3. Save

From then on, fill in Original Invoice with the invoice number (for example 1042) every time you create a credit memo or refund receipt.

How FiscoBridge finds the original invoice

FiscoBridge looks for the original invoice in this order and uses the first match:

  1. Original Invoice custom field (any custom field on the form works)
  2. The credit memo's memo
  3. The message displayed on the credit memo

Each of these can contain other words too, such as Return for invoice 1042. The fiscal receipt number also works. Only invoices of the same customer that FiscoBridge has fiscalized are considered.

If none of these name an invoice, the credit memo or refund receipt is not fiscalized and gets a note asking for the invoice number. FiscoBridge doesn't use the invoice a credit memo is applied to: QuickBooks can apply credits automatically to the customer's oldest open invoice, which is often not the sale being refunded, and a refund reported to the tax authority can't be undone.

Partial credits

A credit memo can cover part of an invoice — the refund contains only the credit memo's own lines and amount. Each fiscal receipt can be refunded only once, so put everything you are crediting for an invoice on a single credit memo.

When a credit memo can't be fiscalized

FiscoBridge adds a note to the credit memo or refund receipt (under Attachments) explaining why, for example:

  • The original invoice wasn't found — fill in Original Invoice and save; the credit memo is picked up again automatically
  • The original invoice isn't fiscalized yet — for example, it's still waiting for payment under When payment is added. The credit memo is fiscalized automatically once the invoice is
  • The reference matches more than one invoice — keep only the original invoice number
  • The fiscal receipt was already refunded or cancelled
  • The credit memo is larger than the original fiscal receipt

Note: A refund that has been reported to the tax authority can't be undone. Deleting or voiding a credit memo in QuickBooks after its refund was fiscalized doesn't reverse the refund; issue a new invoice if the amount is still owed. Refunds count towards your monthly invoice limit like any other fiscal document.

Tax Labels

Every invoice FiscoBridge fiscalizes is reported to the tax authority system, which recognises a fixed set of tax labels — single letters such as A, E, F — and ties each one to a rate (for example Fiji's A · 9% VAT, Samoa's A · 15% VAGST, or Vanuatu's V · 15% VAT). Those labels are the only tax categories the tax authority will accept on a fiscal receipt.

When an invoice comes from QuickBooks, FiscoBridge maps each line's tax code onto one of those tax labels. It does this by name — so your QuickBooks tax rates have to carry names that match the tax labels exactly.

Automatic setup when you connect

You usually don't have to create these tax codes yourself. Every time you connect or reconnect a QuickBooks integration, FiscoBridge looks at the tax labels required for your certificate's country, checks which ones are missing from your QuickBooks company, and creates the missing ones for you automatically — right after you authorize the connection.

For each missing label it adds a new QuickBooks sales tax code with:

  • a tax rate named exactly after the label letter (e.g. A), so it maps straight away, and
  • the percentage the tax authority uses for that label

The tax code is given a readable name (such as VAT or VAGST, falling back to something like A (9%)). The rate is filed under your existing sales tax agency; if your company has none yet, FiscoBridge adds one called Tax Authority, which you can rename in QuickBooks. FiscoBridge only adds missing tax codes — it never edits or deletes tax codes you already have, and any tax code whose rate already matches a label is left untouched.

This is best-effort and never affects the connection itself: if a tax code can't be created — for example, because a tax code or rate with the same name already exists — FiscoBridge skips it and flags the remaining mismatch so you can add it by hand (see What happens if a label doesn't match). Reconnecting retries the creation for any labels that are still missing. Once the tax codes exist, you still need to select them on the relevant invoice lines.

Tax labels by country

The labels and rates depend on the country your certificate was issued for:

Fiji

Label Rate Name
F 0.00 ECAL
N 0.00 N-TAX
P 0.50 PBL
E 0.00 STT
H 5.00 TST
A 9.00 VAT
B 0.00 VAT
D 15.00 VAT
G 12.50 VAT
C 0.00 VAT-EXCL

Samoa

Label Rate Name
N 0.00 N-TAX
A 15.00 VAGST
C 0.00 VAGST-EXCL
B 0.00 VAGST-EXPO

Vanuatu

Label Rate Name
V 15.00 VAT
Z 0.00 VAT-Z

What FiscoBridge matches on

Each QuickBooks tax code contains one or more tax rates (the named percentages inside the code). FiscoBridge looks at the tax rate name. A tax code maps successfully when one of its tax rates is named exactly like a tax label (e.g. a tax rate named A). QuickBooks adds (Sales) to the names of the rates it creates for a tax code, so a rate named A (Sales) matches too. Matching is case-insensitive, but otherwise the name must be the label and nothing else — A and A (Sales) match, VAT A or Standard (A) does not. The built-in TAX and NON codes are ignored.

Setting it up in QuickBooks

  1. In QuickBooks Online, go to Taxes → Sales tax (or Settings ⚙ → Custom sales tax in regions with manual tax)
  2. For each tax label you use, add or edit a tax rate
  3. Set the tax rate name to the tax label letter, exactly: A, E, F, … (if QuickBooks adds (Sales) to the name, leave it)
  4. Set the rate (%) to the rate the tax authority uses for that label (e.g. 9 for Fiji's A · 9% VAT)
  5. Save, then select that tax rate on the relevant invoice line items

Match the rate, not just the name. The label letter is what links the line to the tax authority's category, but you should also set the rate percentage to match the tax authority's rate for that label. If the names line up but the percentages differ, your QuickBooks totals will no longer reconcile with the fiscal receipt.

Combining two labels on one line

A QuickBooks tax code can carry more than one tax label — useful when a line has to be reported under two categories at once, for example Fiji's A (VAT 9%) and F (ECAL). Create a combined tax rate (a tax code that holds more than one rate) and name its two rates A and F. The tax code's own name can be anything (you might call it AF); only the rate names inside it have to be the label letters. The line is then fiscalized under both A and F.

What happens if a label doesn't match

If any line on an invoice uses a tax code that doesn't map to a tax label, the whole invoice is not fiscalized. It is not sent to the tax authority, and no default label is substituted. FiscoBridge records the reason on the invoice — naming the unmapped QuickBooks tax codes, listing the required tax labels, and linking back to this guide — so you can rename the tax rate in QuickBooks and have the invoice synced again.

Checking the status in FiscoBridge

The Integrations page flags any active QuickBooks integration whose tax codes don't match. When there's a mismatch you'll see a Tax labels warning chip on the integration row and a banner that lists:

  • Your unmapped QuickBooks tax codes
  • The required tax labels with their rates (as chips, e.g. A · 9%)

Once you've renamed the tax rates in QuickBooks, click Re-check on the banner to confirm the mismatch is cleared.

OAuth Tokens and Reconnecting

Intuit issues short-lived access tokens alongside long-lived refresh tokens. FiscoBridge refreshes the access token automatically in the background, so you normally don't need to reconnect.

However, Intuit invalidates refresh tokens if:

  • You revoke FiscoBridge's access inside Apps → Connected Apps in QuickBooks
  • The refresh token goes unused for an extended period (Intuit's policy, currently ~100 days)
  • You change the QuickBooks company's primary email or security settings

If the refresh fails, the integration is marked inactive and a Reconnect button appears on its row (same place the Active badge was shown above).

  1. Click Reconnect
  2. Complete the Intuit authorization again
  3. Sync resumes from where it stopped

Previously fiscalized invoices are not affected.

Common Errors

"No organisations were found for the account you authorised." The Intuit account you signed in with isn't a member of any QuickBooks company, or it doesn't have admin rights on the company you meant to connect. Sign out of Intuit, sign back in with the correct admin account, and retry.

Integration suddenly goes inactive. Usually the refresh token was revoked or expired. Reconnect from the integrations list — see above.

Invoices not appearing in FiscoBridge.

  • Confirm the integration status is Active. Inactive integrations don't sync.
  • Check the fiscalization trigger: with When payment is added, an invoice is fiscalized only once it's fully paid.
  • Only invoices with at least one Sales Item line are processed — blank or description-only invoices are skipped.
  • Check your integration license is active and hasn't exceeded its monthly invoice limit.
  • Allow up to 5 minutes for the next check if QuickBooks' notification didn't arrive.

"Line items add up to … but the invoice total is …" The invoice's lines don't add up to its total — usually because of a line type FiscoBridge can't break down, such as a bundle (group) item. Replace the bundle with its individual items, or adjust the lines, and save the invoice; it's picked up again automatically.

Credit memo not fiscalized?

Buyer tax number missing on the fiscal invoice. Open the customer in QuickBooks and make sure the tax number is set on the customer record. QuickBooks invoices don't carry the tax number directly — FiscoBridge fetches it from the linked customer at sync time.

Removing the Integration

  1. Go to Integrations → Integrations
  2. Click Remove next to the QuickBooks integration
  3. Confirm the removal

Removing the integration stops the sync. Previously fiscalized invoices are not affected.

If you also want to revoke FiscoBridge's access on Intuit's side, open QuickBooks → Apps → Connected Apps and disconnect FiscoBridge there — otherwise Intuit keeps the grant recorded against your account.

Next Steps