Pays API

Endpoints

`GET /api/pays/summary`

Get the current user’s pay summary: annual salary, earnings YTD, next pay date.

Permission: view:pays

Response:

{
  "annual_salary": 120000,
  "earnings_ytd": 65000,
  "next_pay_date": "2026-03-13",
  "pay_calendar": "Fortnightly",
  "fy_label": "FY25-26",
  "fetched_at": "2026-03-02T10:00:00"
}

Returns error string and null values if no Xero mapping exists. Returns stale: true if serving cached data because Xero is unavailable.

`GET /api/pays/payslips`

List payslip summaries for the current user, most recent first.

Permission: view:pays

Response:

{
  "payslips": [
    {
      "id": "xero-payslip-id",
      "pay_run_id": "xero-payrun-id",
      "period_start": "2026-02-17",
      "period_end": "2026-02-28",
      "payment_date": "2026-03-01",
      "gross_earnings": 4615.38,
      "net_pay": 3450.00,
      "tax": 965.38,
      "super": 553.85,
      "fetched_at": "2026-03-02T10:00:00"
    }
  ]
}

`GET /api/pays/payslips/:id`

Get full payslip detail including earnings lines, deductions, tax, superannuation, and leave accruals.

Permission: view:pays

Response:

{
  "payslip": {
    "id": "xero-payslip-id",
    "period_start": "2026-02-17",
    "period_end": "2026-02-28",
    "payment_date": "2026-03-01",
    "gross_earnings": 4615.38,
    "net_pay": 3450.00,
    "tax": 965.38,
    "super": 553.85
  },
  "detail": {
    "PayslipID": "xero-payslip-id",
    "EmployeeID": "xero-employee-id",
    "FirstName": "Brendon",
    "LastName": "Smith",
    "NetPay": 3450.00,
    "Tax": 965.38,
    "EarningsLines": [
      { "Name": "Ordinary Hours", "Amount": 4615.38, "NumberOfUnits": 76, "RatePerUnit": 60.73 }
    ],
    "DeductionLines": [],
    "SuperannuationLines": [
      { "ContributionType": "SGC", "Amount": 553.85 }
    ],
    "LeaveAccrualLines": [
      { "Name": "Annual Leave", "NumberOfUnits": 5.85 }
    ]
  }
}

`POST /api/pays/refresh`

Force re-fetch all pay data from Xero (bypasses 4hr cache).

Permission: view:pays

Response: { "ok": true } or { "error": "message" } on failure.

Cache Strategy

TTL: 4 hours
Stale fallback: If Xero is unavailable, previously cached data is served with stale: true
Manual refresh: POST /refresh bypasses TTL and re-fetches from Xero

Prerequisites

Xero connection configured in Settings > Connections
User’s Xero employee ID mapped in Settings > Connections > User Mappings