FiscoBridge Help Main Site

Connecting Xero

Xero is connected through OAuth, which means FiscoBridge securely links to your Xero account without you needing to share passwords. Once connected, your Xero invoices are automatically synced and fiscalized.

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 Xero card

New Integration page showing platform cards with the Xero card highlighted

  1. An Upload Certificate dialog opens — select your PFX certificate file and enter its password, then click Upload

  2. After the certificate is uploaded, the Connect Xero dialog opens. Choose:

    • Fiscalize invoice — when invoices from Xero should be fiscalized (see Fiscalization Trigger below)
    • Receipt format — Receipt slip (journal) or A4 invoice: the layout of the fiscal receipt PDF attached in Xero and offered on the receipt link
    • Training mode — leave off for live fiscal receipts, or turn on to send test (Training) invoices

    Then click Connect

Connect Xero dialog showing the certificate summary, the Fiscalize invoice and Receipt format selectors, and the Training mode switch

Receipt format dropdown with the Receipt slip (journal) and A4 invoice options

  1. You'll be redirected to Xero's authorization page
  2. Log in to your Xero account (if not already logged in)
  3. Select the Xero organization you want to connect
  4. Click Allow Access

Xero authorization page asking to select an organization and allow FiscoBridge access

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

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

Right after you authorize, FiscoBridge also creates any tax rates your country's tax labels need that are missing from your Xero organization — existing rates are never changed. You still need to assign these rates to the line items on your invoices; see Automatic setup when you connect.

Integrations list showing the Xero integration with Active status badge

Fiscalization Trigger

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

Fiscalize invoice dropdown with the When payment is added and When invoice is approved options

When payment is added (default)

The invoice is fiscalized once it's fully paid in Xero (its status becomes Paid).

  • Best when you want the fiscal receipt to reflect the moment of payment
  • Works well for businesses that mark invoices as paid in Xero at the time of sale
  • Unpaid invoices stay in Xero without being sent to the tax authority
  • Partially paid invoices are not fiscalized until the balance reaches zero

When invoice is approved

The invoice is fiscalized as soon as it moves from Draft to Awaiting Payment (approved) in Xero.

  • Best when you issue the fiscal receipt at the moment of sale, regardless of payment status
  • Useful for credit sales where the customer pays later but the invoice is finalized immediately
  • Each approved Xero invoice triggers fiscalization, even if no payment has been recorded yet
  • You can keep an invoice in Draft and edit it as many times as needed — fiscalization only happens once you approve it

Note: To change the trigger, receipt format or training mode later, open the ⋮ menu on the Xero 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 Xero are automatically pulled into FiscoBridge
  • Each invoice is fiscalized (signed and reported to the tax authority) only once. Changes made in Xero after an invoice is fiscalized don't affect its fiscal receipt — raise a credit note and a new invoice if the amount has to change
  • If an invoice fails to fiscalize, fix the problem and save the invoice in Xero — the updated invoice is picked up again automatically
  • Fiscal status is linked back — you can view the Xero invoice directly from the Invoices page
  • The fiscal receipt is attached to the Xero invoice as a PDF (slip or A4, per your Receipt format), and a history note records the fiscal invoice number and verification link
  • Credit notes you raise for customers are fiscalized as refunds of the original fiscal receipt — see Credit Notes
  • Invoices with amounts tax exclusive, tax inclusive or no tax are all supported — the fiscal receipt total always matches the Xero invoice total

Your customer sees the fiscal PDF

The fiscal receipt PDF is shared on Xero's online invoice, so your customer can view and download it from the same link they use to see and pay the invoice.

  • Training invoices are not shared — their PDFs stay visible only to users in your Xero organisation, so test receipts never reach your customers
  • If you fiscalize when payment is added, your customer has usually received the invoice already; the PDF appears on the online invoice once fiscalization completes

Credit Notes

When you raise a credit note for a customer in Xero, FiscoBridge fiscalizes it as a refund of the original fiscal receipt. The refund PDF is attached to the credit note, and a history note records the fiscal refund number and verification link.

When a credit note is fiscalized

Credit notes follow the same fiscalization trigger as your invoices:

  • When payment is added — the credit note is fiscalized once it is fully applied to invoices or refunded to the customer (status Paid)
  • When invoice is approved — the credit note is fiscalized as soon as it is approved

Draft credit notes are never fiscalized, and supplier credit notes are ignored.

Linking a credit note to its original invoice

A refund must point to the fiscal receipt it reverses, so FiscoBridge needs to know which invoice the credit note is for:

  1. Reference — enter the original invoice number (for example INV-0042) in the credit note's Reference field. Other words are fine too, such as Refund INV-0042 damaged item. The fiscal receipt number also works.
  2. Applied invoice — if Reference doesn't name a fiscalized invoice, FiscoBridge uses the invoice the credit note is applied to, as long as that invoice is dated on or before the credit note.

Tip: Xero can't apply a credit note to an invoice that is already paid, so for paid invoices always fill in Reference.

Partial credit notes

A credit note can cover part of an invoice — the refund contains only the credit note'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 note.

When a credit note can't be fiscalized

FiscoBridge adds a note to the credit note's History in Xero explaining why, for example:

  • The original invoice wasn't found — add the original invoice number to Reference and save; the credit note is picked up again automatically. If Xero won't let you edit a credit note that is already applied, remove the allocation, update Reference, then apply it again.
  • Reference names more than one fiscalized invoice — keep only the original invoice number
  • The fiscal receipt was already refunded or cancelled
  • The credit note is larger than the original fiscal receipt
  • A line's tax rate doesn't match a fiscal tax label — see Tax Labels

If a credit note is applied to an invoice that hasn't been fiscalized yet, FiscoBridge checks the credit note again once that invoice is fiscalized.

Voiding a credit note

A fiscal refund that has already been issued can't be reversed by voiding the credit note in Xero. FiscoBridge adds a note to the credit note; if the amount is still owed, issue a new invoice in Xero.

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 Xero, FiscoBridge maps each line's Xero tax rate onto one of those tax labels. It does this by name — so your Xero 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 rates yourself. Every time you connect or reconnect a Xero integration, FiscoBridge looks at the tax labels required for your certificate's country, checks which ones are missing from your Xero organization, and creates the missing ones for you automatically — right after you authorize the connection.

For each missing label it adds a new Xero tax rate with:

  • a tax component 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 rate is given a readable display name (such as VAT or VAGST, falling back to something like A (9%)). FiscoBridge only adds missing rates — it never edits or deletes tax rates you already have, and any rate whose component already matches a label is left untouched.

This is best-effort: if a rate can't be created — for example, if the connected Xero user doesn't have permission to manage tax rates — FiscoBridge skips it and flags the remaining mismatch so you can add it by hand (see What happens if a label fails to match). Reconnecting retries the creation for any labels that are still missing. Once the rates exist, you still need to assign them to the relevant line items on your invoices.

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 Xero tax rate is made up of one or more tax rate components (the named percentage lines inside a tax rate). FiscoBridge looks at the component name, not the tax rate's display name. A component maps successfully when it is named exactly like a tax label (e.g. a component named A). Matching is case-insensitive, but otherwise the name must be the label and nothing else — A matches, VAT A or Standard (A) does not.

Setting it up manually in Xero

If you'd rather set the rates up yourself — or you need to add one that couldn't be created automatically:

  1. In Xero, go to Accounting → Advanced → Tax rates
  2. Add or edit a tax rate for each tax label you use
  3. Give the tax rate any display name you like (e.g. Standard Rate), then set its tax component:
    • Component name — the tax label letter, exactly: A, E, F, …
    • Percentage — the rate the tax authority uses for that label (e.g. 9 for Fiji's A · 9% VAT)
  4. Save the tax rate, then assign it to the relevant line items on your invoices

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 component percentage to match the tax authority's rate for that label. If the names line up but the percentages differ, your Xero totals will no longer reconcile with the fiscal receipt.

Only tax rates that can apply to revenue (sales) are considered — purchase-only rates are ignored.

Combining two labels on one line

A single Xero tax rate 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 one tax rate with two components, name one component A and the other F, and set each component's percentage to its label's rate. The tax rate's display name can be anything (you might call it AF); only the component names have to be the label letters. The line is then fiscalized under both A and F.

What happens if a label fails to match

If any line on an invoice uses a tax rate 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 Xero tax rates, listing the required tax labels, and linking back to this guide — so you can fix the tax rate in Xero and re-approve the invoice.

Lines that carry no quantity, unit price or line amount — description-only lines used as headings or notes — are ignored and don't need a tax rate. Every line that has an amount must use a mapped tax rate.

Checking the status in FiscoBridge

The Integrations page flags any active Xero integration whose tax rates 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 Xero tax rates
  • The required tax labels with their rates (as chips, e.g. A · 9%)

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

Reconnecting

If the connection expires or is interrupted:

  1. Go to Integrations → Integrations
  2. Find your Xero integration in the list
  3. Click the Reconnect button

Xero integration row in the list with the Reconnect button visible for an inactive integration

  1. Complete the Xero authorization again

Note: Xero OAuth tokens expire periodically. If you see your integration marked as inactive, reconnecting will restore the sync.

Reconnecting also re-runs the automatic tax rate setup, so any tax labels still missing from your Xero organization are created again on reconnect.

Viewing Synced Invoices

Invoices synced from Xero appear in Web Invoicing → Invoices. Each synced invoice includes a View in Xero link in its details dialog, taking you directly to the invoice in your Xero account.

Removing the Integration

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

Remove integration confirmation dialog asking to confirm disconnecting the Xero integration

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

Troubleshooting

Invoices not syncing?

  • Check that the integration status is Active
  • Try reconnecting if the status shows as inactive
  • Make sure your integration license is active and hasn't exceeded its invoice limit

"Line items add up to … but the invoice total is …" note on an invoice?

  • The invoice lines don't add up to the Xero invoice total, so FiscoBridge didn't fiscalize it rather than report a wrong amount. Check the invoice for adjustments that aren't line items, correct it in Xero, and it will be picked up again

Credit note not fiscalized?

  • Check the fiscalization trigger: with When payment is added, a credit note is fiscalized only once it's fully applied to invoices or refunded (status Paid)
  • Make sure Reference holds the original invoice number, or that the credit note is applied to the original invoice
  • Open the credit note's History in Xero — a FiscoBridge note explains why. See When a credit note can't be fiscalized

Wrong Xero organization?

  • Remove the current integration and create a new one, selecting the correct organization during the Xero authorization step

Next Steps