FinalPayRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/calculate-co-nz/json-schema/calculate-co-nz-final-pay-request-schema.json",
  "title": "FinalPayRequest",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/calculate-co-nz-openapi.json#/components/schemas/FinalPayRequest",
  "properties": {
    "annual_salary": {
      "type": "number",
      "minimum": 0.0,
      "title": "Annual Salary",
      "description": "Annual salary. Give this OR hourly_rate.",
      "default": 0.0
    },
    "hourly_rate": {
      "type": "number",
      "minimum": 0.0,
      "title": "Hourly Rate",
      "description": "Hourly rate, used with hours_per_week when there is no salary.",
      "default": 0.0
    },
    "hours_per_week": {
      "type": "number",
      "minimum": 0.0,
      "title": "Hours Per Week",
      "description": "Ordinary hours a week. Only used with hourly_rate.",
      "default": 40.0
    },
    "service": {
      "type": "string",
      "title": "Service",
      "description": "over12 for twelve months service or more, under12 for less. This picks the calculation: under twelve months the payout is 8% of gross earnings, not a leave balance; over twelve months it is the untaken entitlement PLUS 8% of the earnings since the last anniversary.",
      "default": "over12"
    },
    "leave_balance_days": {
      "type": "number",
      "minimum": 0.0,
      "title": "Leave Balance Days",
      "description": "Over 12 months: the untaken annual holiday ENTITLEMENT from completed years, in working days. Not a payslip leave balance that includes leave accruing since the last anniversary: the 8% pays for that part, and MBIE says paying out an accrued balance is non-compliant and may underpay.",
      "default": 0.0
    },
    "gross_earnings_total": {
      "type": "number",
      "minimum": 0.0,
      "title": "Gross Earnings Total",
      "description": "Total gross earned across the whole employment. Required when service is under12, where the payout is 8% of it.",
      "default": 0.0
    },
    "average_weekly_earnings": {
      "type": "number",
      "minimum": 0.0,
      "title": "Average Weekly Earnings",
      "description": "Optional 12 month average weekly earnings. The Holidays Act pays leave at the greater of this and ordinary weekly pay; supply it and the higher of the two is used.",
      "default": 0.0
    },
    "notice_weeks": {
      "type": "number",
      "minimum": 0.0,
      "title": "Notice Weeks",
      "description": "Weeks of notice paid in lieu. The notice pay counts towards the 8% (MBIE guidance).",
      "default": 0.0
    },
    "redundancy": {
      "type": "number",
      "minimum": 0.0,
      "title": "Redundancy",
      "description": "Agreed redundancy compensation from the employment agreement. New Zealand has no statutory minimum, so this is an input.",
      "default": 0.0
    },
    "earnings_since_anniversary": {
      "type": "number",
      "minimum": 0.0,
      "title": "Earnings Since Anniversary",
      "description": "Over 12 months: gross earnings since the last work anniversary, including the final wages and any bonus or commission in the final pay. 8% of this plus the leave, holidays and notice pay paid out is owed on top of the untaken entitlement (Holidays Act s25, s26). Left at 0, the 8% is taken on the payouts alone.",
      "default": 0.0
    },
    "public_holidays_days": {
      "type": "number",
      "minimum": 0.0,
      "title": "Public Holidays Days",
      "description": "Over 12 months: public holidays on otherwise working days that would fall in the period the untaken entitlement would cover if taken straight after the last day (s40). Ignored when leave_balance_days is 0.",
      "default": 0.0
    },
    "alternative_holidays_days": {
      "type": "number",
      "minimum": 0.0,
      "title": "Alternative Holidays Days",
      "description": "Alternative holidays owed and not taken (s60), paid at the daily rate.",
      "default": 0.0
    },
    "relevant_daily_pay": {
      "type": "number",
      "minimum": 0.0,
      "title": "Relevant Daily Pay",
      "description": "Optional daily rate for public and alternative holidays, for the last day of employment. When 0, weekly pay / days_per_week.",
      "default": 0.0
    },
    "holiday_pay_already_paid": {
      "type": "number",
      "minimum": 0.0,
      "title": "Holiday Pay Already Paid",
      "description": "Annual holiday pay already paid in advance or as pay as you go, which comes off the 8% (s23(2), s25(2)). The 8% never goes below 0.",
      "default": 0.0
    },
    "days_per_week": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 7.0,
          "exclusiveMinimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Days Per Week",
      "description": "Days worked in a normal week, to turn weekly pay into a daily rate. Default 5. A four day worker's four weeks is 16 days."
    },
    "redundancy_in_eight_percent_base": {
      "type": "boolean",
      "title": "Redundancy In Eight Percent Base",
      "description": "Include redundancy compensation in the 8% base. MBIE's position is that it is not gross earnings; the courts have not decided it, and MBIE says including it minimises the risk.",
      "default": false
    }
  },
  "type": "object"
}