HolidayPayRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/calculate-co-nz/json-schema/calculate-co-nz-holiday-pay-request-schema.json",
  "title": "HolidayPayRequest",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/calculate-co-nz-openapi.json#/components/schemas/HolidayPayRequest",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "annual_leave",
        "pay_as_you_go",
        "public_holiday",
        "termination"
      ],
      "title": "Mode",
      "description": "Which calculation: annual_leave (leave taken, greater of OWP and AWE), pay_as_you_go (8% for casual or short fixed-term staff), public_holiday (worked or not), or termination (leave payout).",
      "default": "annual_leave"
    },
    "ordinary_weekly_pay": {
      "type": "number",
      "minimum": 0.0,
      "title": "Ordinary Weekly Pay",
      "description": "Ordinary weekly pay: what a normal week earns.",
      "default": 0
    },
    "gross_earnings_last_52_weeks": {
      "type": "number",
      "minimum": 0.0,
      "title": "Gross Earnings Last 52 Weeks",
      "description": "Gross earnings for the 12 months up to the end of the last pay period before the holiday, including overtime, commission and earlier holiday pay. Divided by 52 for AWE (s21), and by days_worked_last_52_weeks for average daily pay (s9A).",
      "default": 0
    },
    "leave_weeks": {
      "type": "number",
      "minimum": 0.0,
      "title": "Leave Weeks",
      "description": "Weeks of annual leave taken (annual_leave).",
      "default": 0
    },
    "gross_pay_period": {
      "type": "number",
      "minimum": 0.0,
      "title": "Gross Pay Period",
      "description": "Gross pay for the period BEFORE the 8% loading (pay_as_you_go).",
      "default": 0
    },
    "employment_type": {
      "type": "string",
      "enum": [
        "casual-genuine",
        "casual-doubtful",
        "fixed-term-under",
        "fixed-term-over",
        "permanent"
      ],
      "title": "Employment Type",
      "description": "Employment type, which decides whether 8% PAYG is lawful.",
      "default": "casual-genuine"
    },
    "in_agreement": {
      "type": "boolean",
      "title": "In Agreement",
      "description": "8% PAYG is written into the employment agreement.",
      "default": true
    },
    "payslip_identified": {
      "type": "boolean",
      "title": "Payslip Identified",
      "description": "The 8% is an identifiable part of each pay (s28(1)(c)); its own payslip line is Employment New Zealand's good practice.",
      "default": true
    },
    "pay_periods_per_year": {
      "type": "integer",
      "minimum": 1.0,
      "title": "Pay Periods Per Year",
      "description": "Pay periods a year, for the annual equivalent of the 8% loading: 52 weekly, 26 fortnightly, 12 monthly (pay_as_you_go).",
      "default": 52
    },
    "worked": {
      "type": "boolean",
      "title": "Worked",
      "description": "The public holiday was worked (public_holiday).",
      "default": true
    },
    "otherwise_working_day": {
      "type": "boolean",
      "title": "Otherwise Working Day",
      "description": "The holiday falls on a day the employee would otherwise work. Decides the alternative holiday.",
      "default": true
    },
    "hours_worked": {
      "type": "number",
      "minimum": 0.0,
      "title": "Hours Worked",
      "description": "Hours worked on the public holiday.",
      "default": 0
    },
    "hourly_rate": {
      "type": "number",
      "minimum": 0.0,
      "title": "Hourly Rate",
      "description": "Ordinary hourly rate. For a holiday worked it stands in for the hourly portion of relevant daily pay (s50).",
      "default": 0
    },
    "normal_hours": {
      "type": "number",
      "minimum": 0.0,
      "title": "Normal Hours",
      "description": "Hours the employee would have worked that day, for relevant daily pay.",
      "default": 0
    },
    "multiplier": {
      "type": "number",
      "minimum": 1.5,
      "title": "Multiplier",
      "description": "Public holiday rate: at least 1.5, more if the agreement says so.",
      "default": 1.5
    },
    "public_holiday_days": {
      "type": "number",
      "minimum": 0.0,
      "title": "Public Holiday Days",
      "description": "Public holidays not worked on otherwise working days, each paid at the daily rate.",
      "default": 1
    },
    "daily_pay_method": {
      "type": "string",
      "enum": [
        "auto",
        "relevant",
        "average"
      ],
      "title": "Daily Pay Method",
      "description": "How a day is valued: relevant daily pay (hourly_rate x normal_hours, s9), average daily pay (52 weeks of gross earnings / days_worked_last_52_weeks, s9A, only where relevant daily pay cannot practicably be determined or varies within the pay period), or auto (relevant when given, else average).",
      "default": "auto"
    },
    "days_worked_last_52_weeks": {
      "type": "number",
      "minimum": 0.0,
      "title": "Days Worked Last 52 Weeks",
      "description": "Days worked, or on paid holidays and leave, in the 52 weeks, for average daily pay.",
      "default": 0
    },
    "service": {
      "type": "string",
      "enum": [
        "over12",
        "under12"
      ],
      "title": "Service",
      "description": "Termination: over12 (untaken entitlement plus 8% since the last anniversary) or under12 (no entitlement yet: 8% of earnings since employment began, s23; untaken_weeks must be 0 and no s40 public holidays).",
      "default": "over12"
    },
    "untaken_weeks": {
      "type": "number",
      "minimum": 0.0,
      "title": "Untaken Weeks",
      "description": "Untaken annual holiday ENTITLEMENT from completed years, in weeks (termination). Not a payslip balance that includes leave accruing since the last anniversary: the 8% pays for that.",
      "default": 0
    },
    "earnings_since_anniversary": {
      "type": "number",
      "minimum": 0.0,
      "title": "Earnings Since Anniversary",
      "description": "Gross earnings since the last anniversary, including the final wages (termination). The payouts are added to it for the 8%.",
      "default": 0
    },
    "public_holidays_in_leave_period": {
      "type": "number",
      "minimum": 0.0,
      "title": "Public Holidays In Leave Period",
      "description": "Public holidays on otherwise working days that would fall in the period the untaken leave would cover if taken straight after the last day (termination, s40).",
      "default": 0
    },
    "alternative_holidays_owed": {
      "type": "number",
      "minimum": 0.0,
      "title": "Alternative Holidays Owed",
      "description": "Alternative holidays not taken (termination, s60).",
      "default": 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% (termination).",
      "default": 0
    }
  },
  "type": "object"
}