Expenses, Invoices, and Xero

Expenses are separate from timesheets, but finance and invoice outputs can combine approved expense amounts with timesheet labour/material/allowance amounts.

Expense lifecycle

ExpenseStatus values are draft, submitted, accepted, approved, and rejected.

Typical flow:

1. Electrician creates and submits an expense with project, category, amount, and attachment evidence.
2. Supervisor accepts or rejects submitted expense records.
3. Payroll or Client Admin approves accepted expenses.
4. Approved expenses can be included in invoice/Xero workflows.

Invoice calculation behavior

The existing calculation documentation describes two paths:

If current TimesheetCalculation.billTotal > 0:
    timesheet invoice amount = award bill total + material total

Otherwise:
    timesheet invoice amount = timesheet total hours x matching client base rate + allowance total + material total

Expense invoice lines are separate:

expense invoice amount = approved expense amount

Invoice subtotal is the sum of timesheet invoice amounts and expense invoice amounts. Tax is currently documented as zero at the invoice aggregate level, while award line billing GST can be stored inside award calculation lines when enabled.

Invoice services

Xero integration

Xero is integrated through OAuth and service wrappers:

• XeroAuthController handles /xero/auth, /xero/callback, /xero/test, and /xero/disconnect.
• XeroToken stores token state.
• XeroClient, XeroIntegrationService, and XeroBillSubmissionService perform API work.
• SubmitExpensesTimesheetsToXeroCommand supports command-line submission flows.

Xero routes are authenticated browser routes, not public API endpoints.