Payroll Tax Calculator

Pay Item	Amount ($)	State	Treatment	Adj. Amount	Remove
Loading from Xero...

Contractor Name	Company	State	Classification	Wages ($)	Super ($)
Total	$0.00	$0.00

Entity	Annual Wages ($)
Group Total	$0

Quick Start ▼

The app has 8 tabs. The Dashboard is your home screen. For calculations, follow tabs 1–5 in order:

Dashboard → 1. Pay Runs → 2. Adjustments → 3. Contractors → 4. Results → 5. Export

History, Settings tabs, and the Dashboard are available anytime.

First-Time Setup (2 minutes)

Click Connect to Xero in the header bar
Authorise the app in Xero's consent screen
You'll return to the app — the Dashboard shows your KPIs and alerts

If you manage multiple Xero files, use the org switcher dropdown (next to the status) to switch between them.

Monthly Calculation (5 minutes)

Select Month and Year at the top of the Pay Runs tab
Click Load Pay Runs for Month — select the pay runs to include
Review the Adjustments tab — deductions are auto-detected from payslips
Add any Contractors with relevant contracts
Click Calculate Payroll Tax
Review the Results — save to history and export to Excel

Xero Connection ▼

Connecting

Click the Connect to Xero button in the header. You'll be redirected to Xero to authorise access to payroll data (employees, pay runs, payslips). Once authorised, you're returned to the app.

Example

Header shows: ● Connected — ABC Pty Ltd [Disconnect]

Switching Xero Files

If your Xero login has access to multiple organisations, a dropdown appears next to the connection status. Select a different org to switch — all data (pay runs, employees, history) is isolated per Xero file.

Disconnecting

Click Disconnect next to the status. This removes the stored Xero tokens. You can reconnect at any time — no data is lost.

Troubleshooting

Connection expired: Xero tokens refresh automatically. If you see "Not connected", click Connect to Xero again.
Wrong organisation: Use the org switcher dropdown, or disconnect and reconnect selecting the correct org in Xero's consent screen.
No pay runs found: Ensure the selected month has finalised pay runs in Xero. Draft pay runs are not returned.

Dashboard ▼

The Dashboard is the first screen you see after logging in. It gives you an at-a-glance overview of your payroll tax position.

KPI Cards (Top Row)

Four summary cards across the top:

What you'll see

+------------------+------------------+------------------+------------------+
| Current Month    | YTD Tax          | Open Exceptions  | Next Lodgement   |
| Tax              |                  |                  |                  |
|   $12,345.00     |   $98,765.00     |   3              |   12d            |
|                  |                  |                  |   NSW — 2026-04-07|
+------------------+------------------+------------------+------------------+

Current Month Tax — total payroll tax for the current calendar month
YTD Tax — sum of all monthly taxes for the current financial year
Open Exceptions — number of unresolved review tasks (shown in orange if > 0)
Next Lodgement — days until your next state lodgement deadline, with state and date

Monthly Tax Trend (Bar Chart)

A 12-month bar chart showing your payroll tax for each month of the current financial year (Jul–Jun). Empty months show a flat gray bar. Hover over any bar to see the exact amount.

Example chart

           $15K
  $12K      |
   |   $10K |        $11K
   |    |   |    $9K  |
   |    |   |     |   |
  Jul  Aug  Sep  Oct  Nov  Dec  Jan  Feb  Mar  ...

Quick Actions (Right Panel)

Three buttons for the most common tasks:

Calculate Current Month — jumps to the Pay Runs tab
View History — jumps to the History tab
Year Reconciliation — opens the FY reconciliation modal

Recent Calculations

A table showing your last 5 saved calculations with period, organisation, tax amount, and status (Draft, Locked, or Approved).

Upcoming Lodgements

A table of your next upcoming lodgement deadlines by state, with due dates and status. Overdue deadlines are highlighted in red.

Alert Banner

A coloured banner appears at the top if there are issues requiring attention:

Red — overdue lodgement deadlines
Amber — unverified rates for the current FY, or pending ruleset candidates

Tab 1 — Pay Runs ▼

Selecting the Period

Choose the Month and Year. Optionally filter by pay frequency (Weekly, Fortnightly, Monthly) or show All Pay Runs. The app auto-calculates the number of days in the period including leap years. Payroll tax is always lodged monthly — the threshold is annual ÷ 12 regardless of pay frequency.

Loading Pay Runs

Click Load Pay Runs for Month. The app fetches all finalised pay runs from Xero whose payment date falls within the selected month.

Example

Period: March 2026 → fetches pay runs paid between 1 Mar and 31 Mar 2026.

Selecting Pay Runs

Each pay run shows the pay date, number of employees, and total wages. Tick the checkbox to include it in the calculation.

Select All: Includes every pay run for the month
Clear: Deselects all pay runs

If you run weekly and monthly payrolls, you can select all of them together — the app combines all selected pay runs into one calculation.

Common Mistakes

Selecting pay runs from the wrong month — always check the payment date, not the pay period
Forgetting fortnightly runs that span month boundaries — allocate to the month the payment date falls in
Not loading all pay frequencies — if you run weekly and monthly payrolls, load both

Relevant Legislation NSW — Payroll Tax Act 2007 VIC — Payroll Tax Act 2007 QLD — Payroll Tax Act 1971 SA — Payroll Tax Act 2009 WA — Pay-roll Tax Assessment Act 2002 TAS — Payroll Tax Act 2008 NT — Payroll Tax Act 2009 ACT — Payroll Tax Act 2011

Next Step

Click Next: Adjustments → to proceed (or click the Adjustments tab directly).

Tab 2 — Adjustments ▼

Allowances & Deductions (Auto-Detected)

The app scans Xero payslip data and auto-detects pay items like mileage, allowances, salary sacrifice, and novated leases. Each item shows:

Pay Item — name from Xero
Amount — value from payslip
Treatment — dropdown: Taxable, Exempt, or Salary Sacrifice

You can override the amount or change the treatment. Click + Add Item Manually to add items not in Xero.

Example

A "Motor Vehicle Allowance" is auto-detected at $850. Change treatment to Exempt to exclude it from the payroll tax base.

Directors Remuneration

Enter a dollar amount to deduct directors' fees from the payroll tax base. Or use the Manage Directors button to tag specific employees as directors — their wages are automatically deducted each calculation.

How to tag directors

Click Manage Directors in the Directors Remuneration row
A modal shows all employees from Xero
Tick the checkbox next to each director's name
Close the modal — tagged directors persist across calculations

Director remuneration is taxable wages in most Australian states (NSW, VIC, WA, SA). Tag directors for record-keeping, but enter any exempt amounts manually under Directors Fees after professional review.

Other National Deductions

Paid Parental Leave — Commonwealth-funded PPL is exempt from payroll tax
Workers Compensation — premiums to deduct
Termination (Tax-Free) — genuine redundancy tax-free amounts

Per-State Additions

Add state-specific taxable amounts (e.g., FBT grossed-up values, interstate wages allocated to a specific state). Click + Add State Adjustment, select the state, and enter the amount.

Example

Your company has $12,000 FBT for NSW employees. Add a State Adjustment: NSW, Amount: $12,000.

State-Specific Exemptions

VIC Regional Employer — tick if eligible for the reduced 1.2125% rate for regional Victorian payrolls
NT Apprentice & Trainee Wages — enter monthly exempt wages (available from 1 July 2025)
ACT GP Wages (Bulk-Billed) — enter monthly exempt GP wages (available from 1 July 2025)

Group Employer & SA Estimate

Annual Group Wages — if you're part of a designated group employer (DGE), enter total group wages here. This affects threshold entitlement across all states.
SA Annualised AU Wages Estimate — override the default annualisation for SA's transitional rate band ($1.5M–$1.7M). Leave blank to use the default.

Common Mistakes

Not deducting genuine salary sacrifice — pre-tax salary sacrifice reduces the payroll tax base in all states
Incorrectly marking allowances as exempt without checking state rules — each state has different exempt allowance categories
Forgetting FBT grossed-up values — fringe benefits are taxable wages and must include the gross-up factor

Relevant Legislation — Exemptions NSW — Exemptions (Payroll Tax Act 2007 ss 40-50) VIC — Exemptions (Payroll Tax Act 2007 Part 4) QLD — Exemptions (Payroll Tax Act 1971) SA — Exemptions (Payroll Tax Act 2009)

Tab 3 — Contractors ▼

When to Add Contractors

Contractor payments are taxable for payroll tax only when a relevant contract exists (in harmonised states). This typically includes labour-hire arrangements and certain service contracts where the contractor works primarily for your business.

WA Exception: Western Australia does not use the relevant contract test — different rules apply. Consult your adviser for WA contractor obligations.

Adding Contractors Manually

Click + Add Contractor
Fill in: Name, Company, State (where work performed), Classification, Wages, and Super
Repeat for each contractor

Example

Contractor: Jane Smith, Company: Smith Consulting, State: VIC, Classification: Relevant Contract, Wages: $8,500, Super: $935

Classifications

Relevant Contract — contractor under a relevant contract (taxable)
Employment Agency — on-hired worker via an employment agency (taxable)
Exempt — exempt from payroll tax (e.g., registered charities)
Excluded — not subject to payroll tax
Review Required — insufficient information to classify, flagged for review

Saved Contractor Records

The Saved Contractors section at the top of the Contractors tab stores persistent contractor records with classification history. When you run a calculation, saved contractors are automatically matched by name or ABN and their classification is applied.

Click + Add Record to create a persistent contractor with name, ABN, state, and classification
Click Load into Calculation to copy saved contractors into the current calculation
Classification changes are tracked with history (who changed what, when)

CSV Import (Bulk)

For many contractors, use the CSV import:

Click Download Template to get the CSV format
Fill in your contractor data (columns: Name, Company, State, Wages, Super)
Click Import CSV and select your file

The template includes example rows showing the expected format. State must be a valid abbreviation: NSW, VIC, QLD, SA, WA, TAS, NT, or ACT.

Common Mistakes

Including all contractor payments — only payments under a "relevant contract" are taxable wages
Omitting employment agency contracts — payments to employment agencies are generally taxable
Applying harmonised rules to WA — WA has its own contractor provisions under the Pay-roll Tax Assessment Act 2002

Relevant Legislation — Contractors Harmonised Relevant Contract Test (all states except WA) WA — Pay-roll Tax Assessment Act 2002 (Contractor Provisions)

Next Step

Click Calculate Payroll Tax to run the calculation. The app combines employees (from Xero pay runs), adjustments, and contractor wages into the final payroll tax estimate.

Tab 4 — Results ▼

How the Calculation Works

The app fetches payslip details from Xero for all selected pay runs
Each employee is allocated to a state based on their home address in Xero
Interstate apportionment is applied: monthly threshold × (state wages ÷ total AU wages)
Per-state payroll tax is calculated using each state's rate and threshold

National Summary

Shows totals across all states: gross wages, employer super (SGC), deductions, contractor wages, and the net payroll tax base.

State Breakdown Cards

Each state with wages shows a card displaying:

Employee wages + super for that state
Deductions and contractor wages allocated to the state
Interstate wages (from other states — used for apportionment)
Monthly threshold (proportionally apportioned)
Taxable wages (above threshold)
Tax rate and monthly payroll tax amount

Example — NSW card

NSW Wages: $85,000 • Super: $9,350 • Monthly Threshold: $100,000 • Taxable: $0 • Tax: $0.00
(Wages below threshold — no tax for this month)

Employee Allocation Table

Below the state cards, a table lists every employee with their allocated state and nexus method (Home Address, Nexus Override, ABN Fallback, or Postcode Fallback).

Compliance Warnings

A yellow banner appears if the app detects issues:

Unknown State Employees — employees whose home address couldn't be resolved to a state. Update their address in Xero or set a Nexus Override in Settings.
Exception Tasks — clickable panel listing items to review (Nexus Review, Contractor Review, Group Config, SA Estimate, etc.)

Home-address allocation may not match harmonised nexus rules for interstate or mobile workers. Use Nexus Overrides (in Settings) for employees who work in a different state to their home address.

Common Mistakes

Not reviewing employees with UNKNOWN state — check and set nexus overrides in Settings for FIFO or interstate workers
Ignoring exception tasks — red exception banners indicate data quality issues that affect accuracy
Forgetting to verify the nexus for interstate workers — the 4-step harmonised nexus test determines which state taxes apply

Relevant Legislation — Rates & Thresholds NSW Rates & Thresholds VIC Rates & Thresholds QLD Rates & Thresholds SA Rates & Thresholds WA Rates & Thresholds TAS Rates & Thresholds NT Rates & Thresholds ACT Rates & Thresholds

Saving Results

Click Save to History to permanently record this calculation. You can view, export, or delete saved records from the History tab.

Tab 5 — Export ▼

Downloading the Report

After running a calculation, go to the Export tab and click Download Excel Report (.xlsx). The file downloads as payroll-tax-[period].xlsx.

What's in the Workbook

The Excel file contains 5 sheets:

Payroll Tax Summary — overview of all states with monthly tax amounts, thresholds, and rates
State Lodgement Summary — per-state breakdown formatted for lodgement with each state revenue office
Employee Summary — full employee list with state allocation, gross earnings, super, and nexus method
Contractor Workbook — contractor detail by state with classification and amounts
Calculation Evidence — provenance data: ruleset version hash, snapshot hash, financial year, confidence per state, compliance warnings

You can also export individual historical records from the History tab by clicking the XLS button next to any saved record.

Tab 6 — History ▼

Saved Calculations

Every time you click Save to History from the Results tab, a snapshot is stored with the full calculation details, inputs, and results. History records show:

Date saved, period (month/year), organisation name
Financial year, source (Xero or Manual), monthly tax total
Status — Draft, Locked, or Approved (see Period Lock below)
Who saved the record

History table with status

Date       Period     Org          FY      Source  Tax         Status    By       Actions
───────────────────────────────────────────────────────────────────────────────────────────
24 Mar 26  Mar 2026   Cooper Oxley 2025-26 xero    $12,345.00 [Approved] mwiriadi View XLS
24 Feb 26  Feb 2026   Cooper Oxley 2025-26 xero    $11,200.00 [Locked]   mwiriadi View XLS Lock
24 Jan 26  Jan 2026   Cooper Oxley 2025-26 xero    $10,800.00 [Draft]    mwiriadi View XLS Lock Del

Period Lock & Approval Workflow

Calculations go through a three-stage workflow to prevent accidental changes:

Status flow

  Draft  ──[Lock]──▶  Locked  ──[Approve]──▶  Approved
    │                   │                        │
    │  Can edit/delete  │  Cannot overwrite       │  Fully finalised
    │  Can recalculate  │  Admin can unlock       │  Admin can unlock
                        │  Different user can     │
                        │  approve (separation    │
                        │  of duties)             │

Step-by-step:

Save a calculation → it starts as Draft
Click Lock in the Actions column → becomes Locked
A different user clicks Approve → becomes Approved

Rules:

Locked calculations cannot be overwritten — saving a new calculation for the same period is blocked
Only admins can unlock a locked or approved calculation
The person who locked a calculation cannot approve it (separation of duties)
Unlocking also removes any approval
Locked calculations cannot be deleted

Lock and approve your calculations each month for a clean audit trail. The Year Reconciliation view shows lock status for all 12 months.

Lodgement Tracker

Below the history table, the Lodgement Tracker shows all state lodgement deadlines. Deadlines are automatically created when you save a calculation.

Lodgement tracker

State  Period    Due Date    Status      Reference    Actions
──────────────────────────────────────────────────────────────
NSW    3/2026    2026-04-07  [Pending]                [Mark Lodged]
VIC    3/2026    2026-04-07  [Pending]                [Mark Lodged]
WA     3/2026    2026-04-07  [Pending]                [Mark Lodged]
NSW    2/2026    2026-03-07  [Lodged]   REF-20260307
VIC    2/2026    2026-03-07  [Paid]     PMT-456123

Step-by-step:

Save a calculation → deadlines are auto-created for each state in the results
Due dates follow state rules: 7th of following month (NSW, VIC, QLD, SA, WA, TAS, ACT) or 21st (NT)
Click Mark Lodged → enter reference number → status changes to Lodged
Click Mark Paid → enter payment reference → status changes to Paid

Status colours:

Pending — not yet lodged, due date in the future
Overdue — due date has passed and not yet lodged
Lodged — submitted to revenue office
Paid — payment confirmed

Viewing a Record

Click View next to any record to see the full calculation details in a modal. From there you can also export it to Excel.

Adding a Historical Entry

Click + Add Historical Entry to manually record a past calculation (e.g., from before you started using the app).

Year Reconciliation

Click Year Reconciliation to see a period-by-period summary for a full financial year. Shows lock/approval status per month and is useful for annual returns.

Deleting Records

Click Del next to a record (only visible for Draft status). Locked and approved calculations cannot be deleted — an admin must unlock first.

Nexus Overrides ▼

What Are Nexus Overrides?

By default, employees are allocated to a state based on their home address in Xero. Nexus overrides let you manually assign an employee to a different state for payroll tax purposes.

When to Use

FIFO workers — live in one state, work in another
Interstate commuters — principal place of employment differs from home
Mobile workers — work across multiple states
Incorrect Xero address — employee hasn't updated their home address

Example

Employee John Smith lives in QLD but works at a mine site in WA. Set a nexus override: State = WA, Reason = "FIFO — principal place of employment is WA"

How to Set an Override

Go to Settings → Nexus Overrides
Enter the Employee ID (find it in the Results employee table or click an employee row)
Select the Override State
Add a Reason (for audit trail)
Click Set Override

How It Affects Calculations

During calculation, overrides take top priority in the nexus test. The employee's wages are allocated to the override state regardless of their home address. The Results tab shows "Nexus Override" in the nexus method column.

Group Employer (DGE) ▼

What Is a Designated Group Employer?

If your business is part of a group of related entities (e.g., parent company and subsidiaries), payroll tax thresholds are shared across the group. The Designated Group Employer (DGE) is the entity nominated to lodge on behalf of the group.

Configuring the Group

Go to Settings → Group Employer
Click Manage Group
Add each member entity with their name, Xero tenant ID, and annual wages
Set one member as the Designated Group Employer (claims the threshold)
The total group wages determine the shared threshold entitlement

Example

Group: Smith Holdings Group
Members: ABC Pty Ltd ($1.2M), XYZ Pty Ltd ($800K), DEF Pty Ltd ($500K)
DGE: ABC Pty Ltd
Total Group Wages: $2.5M — only ABC claims the threshold.

Important: Group Scoping

Groups are scoped per Xero organisation — each Xero file can have its own group
An entity must be explicitly added as a member of a group to be treated as grouped
Standalone entities (not added to any group) always claim their own full threshold
Non-DGE group members pay tax on 100% of wages with no threshold deduction

Make sure the current Xero organisation is added as a member of the group. If it's not a member, it will be treated as a standalone entity even if a group exists.

In the Adjustments Tab

As an alternative to the database-managed group, you can enter Annual Group Wages manually. This overrides the database group lookup for this calculation only.

In Results

When group wages are active, a banner appears showing: group name, total wages, DGE status, and threshold entitlement.

AI Rate Research (Admin) ▼

What It Does

Uses Claude AI to research the latest payroll tax rates and annual thresholds for all 8 Australian states and territories. This saves manually checking 8 different revenue office websites each financial year.

How to Use

Go to Settings → Payroll Tax Rates
Select the target Financial Year (e.g., 2026-27)
Click Research Rates with AI
Review the comparison table showing current vs AI-proposed rates
Each row includes a source URL — click to verify against the official site
Edit any values if needed
Click Approve & Save All to apply
Click Mark as Verified to confirm rates are checked

Example — AI comparison table

NSW: Current 5.45% / $1.2M → AI Proposed 5.45% / $1.2M • Confidence: High
VIC: Current 4.85% / $700K → AI Proposed 4.85% / $700K • Confidence: High

Always verify AI-proposed rates against the official state revenue office websites before approving. The source URLs are provided for each state. AI confidence levels indicate certainty: High, Medium, or Low.

Annual Rate Update Workflow (July 1)

Copy to New FY — copies current rates as a starting point
Research Rates with AI — get Claude's latest research
Verify — check each rate against official sources
Approve & Save All — apply verified rates
Mark as Verified — record the verification for audit

Two-Factor Authentication ▼

What Is 2FA?

Two-factor authentication adds a second layer of security to your login. After entering your password, you must also enter a 6-digit code from an authenticator app on your phone.

Setting Up 2FA

Go to Settings and find the Two-Factor Authentication section
Click Enable Two-Factor Authentication
Scan the QR code with your authenticator app (Google Authenticator, Authy, Microsoft Authenticator, etc.)
Enter the 6-digit code from the app to confirm
Save your recovery codes in a safe place — they are shown only once

Logging In with 2FA

After entering your password, you'll see a second screen asking for the 6-digit code. Enter the code from your authenticator app. You can optionally tick "Remember this device for 30 days" to skip the 2FA step on this browser.

Recovery Codes

If you lose access to your authenticator app, use one of your 8 single-use recovery codes to log in. Each code can only be used once. You can regenerate codes from the Settings page (requires your password).

Disabling 2FA

Click Disable 2FA in Settings and enter your password to confirm. This removes the TOTP secret and all recovery codes.

Admin accounts are strongly encouraged to enable 2FA. Payroll tax data is sensitive financial information.

Regression Tests (Admin) ▼

What Are Regression Tests?

The regression test suite runs known-good examples against the calculation engine to verify that rates and thresholds produce correct results. This catches errors in rate configuration before they affect real calculations.

Running Tests

Go to Settings → Regression Tests
Click Run Tests
Review the results table — each test shows PASS or FAIL with expected vs actual values

What's Tested

All 8 jurisdictions: NSW, VIC, QLD, SA, WA, TAS, NT, ACT
Boundary conditions: at, above, and below threshold
Surcharge tiers: VIC mental health levy, QLD higher duties surcharge, ACT tiers
Special rules: WA diminishing threshold, SA transitional band
Pro-rata: 28, 29, 30, and 31-day months

Run the regression suite after approving new rates or ruleset candidates to confirm nothing is broken.

Ruleset Candidates (Admin) ▼

What Are Ruleset Candidates?

When the automated rule refresh pipeline (or AI rate research) detects a rate change, it creates a candidate ruleset — a proposed set of rates for a jurisdiction. Candidates must be reviewed and approved before they take effect in calculations.

Reviewing Candidates

Go to Settings → Ruleset Candidates
Each candidate shows a side-by-side diff comparing proposed values against the current approved rates
Changed fields are highlighted (current value struck through, proposed value shown)
Optionally add approval notes explaining why the change is approved
Click Approve to publish the candidate, or Reject to discard it

Ruleset Lifecycle

Candidate — proposed but not yet active. Does not affect calculations.
Approved — active and used in calculations for its effective date range.
Retired — replaced by a newer ruleset or manually archived.

Approval History

The Approval History section shows all previously approved rulesets with the approver name, date, notes, rate, and threshold. Useful for audit trails.

Always run the Regression Tests after approving a new ruleset to verify the new rates produce correct results.

Email Notifications ▼

What Gets Notified

The app can send email alerts for four types of events. Each can be toggled on/off per user:

Notification types

[x] New rate candidates      — when AI detects rate changes
[x] Lodgement deadlines      — 3 days before a deadline
[x] High-severity exceptions — nexus review, missing group config
[x] Period lock/approval     — when a calculation is locked or approved

Setting Up Email Notifications

Step 1: Configure SMTP (admin, one-time)

Set these environment variables in Replit Secrets:

SMTP_HOST — your email server (e.g., smtp.gmail.com)
SMTP_PORT — usually 587 (TLS) or 465 (SSL)
SMTP_USER — email account username
SMTP_PASS — email account password or app password
SMTP_FROM — sender address (e.g., noreply@yourcompany.com)

Step 2: Configure your preferences

Go to Settings → Email Notifications
Enter your email address
Tick the notification types you want to receive
Click Save

Step 3: Test the connection

Click Send Test Email (admin only)
Check your inbox for the test message
If it doesn't arrive, check the SMTP settings in Replit Secrets

For Gmail, use an App Password (not your regular password). Go to Google Account → Security → 2-Step Verification → App Passwords.

Bug Reports & Feature Requests ▼

How to Report a Bug or Request a Feature

You can report issues or request features from two places:

Click your user avatar (top-right) → Report Bug / Feature Request
Scroll to the bottom of this Help drawer and click the button

What Happens When You Submit

A form opens asking for the type (Bug, Feature, or Question), subject, and description
When you click Send Report, the app automatically collects debug information:
- Which tab you were on, your browser and screen size
- Any recent JavaScript errors in your browser
- Server uptime, memory usage, Node.js version
- Your last 15 audit log entries
- Any open exception tasks
Everything is sent as a single email to the support team

Example bug report email

Subject: [Payroll Tax Bug] Calculation shows wrong threshold for VIC

From: Jane Smith (jane@company.com) — Company Pty Ltd
Xero Org: abc123-def456

Description:
When I calculate March 2026, the VIC threshold shows $700K
but it should be $1M.

Debug Context:
  Active Tab: results
  Browser: Chrome 125.0 / macOS
  Screen: 1920x1080
  Node: v20.11.0 | Uptime: 45min | Memory: 82MB heap

Recent Errors: None

Recent Audit Log:
  2026-03-24 10:30  calculation_saved  {period: "Mar 2026"}
  2026-03-24 10:29  login              {username: "jane"}
  ...

The more detail you include in your description, the faster the issue can be resolved. Include what you were doing, what happened, and what you expected.

Admin Settings ▼

Settings Tab (Admin Only)

The Settings tab is visible only to admin users. It contains:

Branding

Customise the app appearance: Company Name, Logo URL, and Primary Colour. Changes apply immediately for all users.

Entity Details / Nexus

ABN Registered State — used as a fallback for employees with unknown home addresses
Principal Place of Business — used in the 4-step nexus test for harmonised states

Set these correctly — they determine the fallback state for employees whose Xero address can't be resolved.

User Management

+ Add User — create a new user with display name, username, email, password, and role (admin or user)
Delete — remove a user account
Change Password — available from the user dropdown menu (top-right)

Two-Factor Authentication

Enable or disable TOTP-based 2FA for your account. See the Two-Factor Authentication section below for details.

Payroll Tax Rates

Per-state configuration showing rate (%), annual threshold ($), and source URL. See the AI Rate Research section above for the annual update workflow.

NSW Monthly Thresholds

NSW uses day-based thresholds that vary by month length. Enter each month's threshold value and click Save NSW Thresholds.

Regression Tests

Run the test suite against current approved rates. Tests include boundary conditions, surcharge tiers, and pro-rata calculations across all 8 jurisdictions. See the Regression Tests section below.

Ruleset Candidates

When the rule refresh pipeline detects rate changes, candidates appear here with a side-by-side diff against the current approved ruleset. Approve or reject each candidate with notes. See the Ruleset Candidates section below.

Approval History

View the audit trail of all approved rulesets: who approved, when, with what notes, and the rate/threshold values.

Audit Log

Click Refresh to view the log of administrative actions: logins, rate changes, user management, Xero connections, 2FA events, calculation events, period lock/approval, and bug reports.

Email Notifications

Configure per-user email alerts for rate candidates, lodgement deadlines, exceptions, and period lock events. See the Email Notifications section above for setup instructions.

Installation Guide ▼

Prerequisites

Node.js 18+ installed
A Xero app created at developer.xero.com (OAuth 2.0 Web App type)

Local Setup

Clone the repository: git clone <repo-url>
Install dependencies: npm install
Copy .env.example to .env and configure:
- XERO_CLIENT_ID and XERO_CLIENT_SECRET from your Xero app
- SESSION_SECRET — a random string for cookie encryption
- ANTHROPIC_API_KEY — optional, for AI rate research
Start the server: npm start (or npm run dev for hot-reload)
Open http://localhost:3000
Create your admin account on the setup screen

Replit Hosting (Current)

Import the GitHub repo into Replit
Set Secrets in Replit: XERO_CLIENT_ID, XERO_CLIENT_SECRET, SESSION_SECRET
Optionally set ANTHROPIC_API_KEY (AI rate research) and TOTP_ENCRYPTION_KEY (2FA secret encryption)
Click Run — the app starts on Replit's provided URL
Set the Replit URL as your Xero app's redirect URI

AWS Sydney (Future Target)

The codebase includes abstraction points for future migration to AWS ap-southeast-2 with PostgreSQL, SQS, and S3. This migration is deferred until the application layer is feature-complete.

Environment Variables

`XERO_CLIENT_ID`	Required	From Xero developer portal
`XERO_CLIENT_SECRET`	Required	From Xero developer portal
`SESSION_SECRET`	Required	Random string for cookie signing
`ANTHROPIC_API_KEY`	Optional	For AI rate research feature
`TOTP_ENCRYPTION_KEY`	Optional	Encryption key for 2FA secrets at rest (falls back to SESSION_SECRET)
`SETUP_TOKEN`	Optional	One-time token for initial admin setup
`ALLOWED_ORIGINS`	Optional	Comma-separated allowed origins for CSRF
`BRAND_NAME`	Optional	White-label company name
`BRAND_COLOUR`	Optional	White-label primary colour (hex)
`BRAND_LOGO_URL`	Optional	White-label logo URL

Maintenance Guide ▼

Updating the App

Push code to GitHub. Pull changes on Replit — the app picks up new code on the next run. Database migrations run automatically on startup.

Data Backup

Replit: Download the data/payroll.db file from the file browser
Local: Copy the data/payroll.db file

Adding a New Client (White-Label)

Deploy a new Replit instance with the client's BRAND_NAME, BRAND_COLOUR, and BRAND_LOGO_URL environment variables. Each client gets an isolated database.

Troubleshooting

"Not connected to Xero" — token expired. Click Connect to Xero to re-authorise.
Employee shows UNKNOWN state — their Xero home address is missing or incomplete. Update in Xero or set a Nexus Override.
No pay runs found — check that pay runs are finalised (not draft) in Xero for the selected period.
Rates not verified banner — an admin needs to verify rates for the current FY in Settings.
Session expired — log in again. Sessions last 24 hours.
"This period is locked" — an admin must unlock the calculation in the History tab before you can save a new one for that period.
Cannot approve own calculation — separation of duties requires a different user to approve. Ask a colleague or admin.
Email notifications not sending — check SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS are set in Replit Secrets. Use "Send Test Email" in Settings to verify.
2FA code rejected — check your phone's clock is accurate. TOTP codes are time-sensitive (30-second window). If locked out, use a recovery code.
Entity not treated as grouped — the current Xero org must be explicitly added as a member of the group in Settings. Standalone entities are never auto-grouped.
Exceptions disappeared after recalculating — each calculation regenerates exceptions for that Xero org only. Exceptions from other orgs are preserved.

Glossary ▼

Payroll Tax Base	Gross wages + employer SGC super contributions + FBT + contractor wages − exempt amounts
SGC	Superannuation Guarantee Charge — compulsory employer super contribution (currently 12%)
FBT	Fringe Benefits Tax — grossed-up taxable value of fringe benefits is included in payroll tax base
Annual Threshold	Total annual wages below which no payroll tax applies. Varies by state (e.g., NSW $1.2M, VIC $1M)
Monthly Threshold	Annual threshold ÷ 12 (or day-based for NSW). Apportioned across states if multi-state employer.
Interstate Apportionment	Proportional threshold = monthly threshold × (state wages ÷ total AU wages)
Nexus	The connection between an employee and a state that determines which state collects payroll tax on their wages
DGE	Designated Group Employer — the entity nominated to lodge and pay payroll tax on behalf of a group of related entities
Relevant Contract	A contractor arrangement that triggers payroll tax obligations (labour-hire, service contracts where contractor works primarily for one business)
Financial Year	1 July to 30 June (e.g., FY 2025-26 = 1 Jul 2025 to 30 Jun 2026)

Create Admin Account

Sign In

Two-Factor Authentication

Set Your Password

Connect to Xero to get started

Monthly Tax Trend

Quick Actions

Recent Calculations

Upcoming Lodgements

Select Pay Period & Pay Runs

Allowances & Deductions

Other Deductions

Per-State Additions

State-Specific Exemptions

Group Employer & SA Estimate

Saved Contractors

Contractors (This Calculation)

National Summary

Allowances Detected

State Breakdown

Export

The export includes the following sheets:

Calculation History

Compliance Report

Provenance History

Lodgement Tracker

🤖 Research New FY Rates with AI

NSW Monthly Thresholds

Help & Guide

First-Time Setup (2 minutes)

Monthly Calculation (5 minutes)

Connecting

Switching Xero Files

Disconnecting

Troubleshooting

KPI Cards (Top Row)

Monthly Tax Trend (Bar Chart)

Quick Actions (Right Panel)

Recent Calculations

Upcoming Lodgements

Alert Banner

Selecting the Period

Loading Pay Runs

Selecting Pay Runs

Next Step

Allowances & Deductions (Auto-Detected)

Directors Remuneration

Other National Deductions

Per-State Additions

State-Specific Exemptions

Group Employer & SA Estimate

When to Add Contractors

Adding Contractors Manually

Classifications

Saved Contractor Records

CSV Import (Bulk)

Next Step

How the Calculation Works

National Summary

State Breakdown Cards

Employee Allocation Table

Compliance Warnings

Saving Results

Downloading the Report

What's in the Workbook

Saved Calculations

Period Lock & Approval Workflow

Lodgement Tracker

Viewing a Record

Adding a Historical Entry

Year Reconciliation

Deleting Records

What Are Nexus Overrides?

When to Use

How to Set an Override

How It Affects Calculations

What Is a Designated Group Employer?

Configuring the Group

Important: Group Scoping

In the Adjustments Tab