Calculate Pay

POST /api/v1/calculate-pay

Request body

Field	Type	Required	Default	Description
award_code	string	Yes	—	Modern Award code (e.g. MA000009)
classification_code	string	Yes	—	Classification level (e.g. HI1, L2Y1, RE3)
employment_type	string	Yes	—	full_time, part_time, or casual
worker_type	string	No	non_shiftworker	non_shiftworker or shiftworker
work_date	string (date)	Yes	—	YYYY-MM-DD format
is_public_holiday	boolean	No	false	Whether the shift falls on a public holiday
start_time	string	No	—	Shift start time HH:MM (24h). Provide with end_time.
end_time	string	No	—	Shift end time HH:MM (24h). Provide with start_time.
unpaid_break_minutes	integer	No	0	Minutes of unpaid break during the shift
total_hours_worked	number	No	—	Alternative to start/end time — specify hours directly
hours_already_worked_today	number	No	0	Hours already worked earlier in the day
hours_already_worked_this_week	number	No	0	Hours already worked this week (triggers weekly overtime)
is_first_aid_officer	boolean	No	false	Whether first aid allowance applies
requires_laundry_allowance	boolean	No	false	Whether laundry allowance applies
is_meal_allowance_triggered	boolean	No	false	Whether meal allowance applies
additional_allowances	object	No	{}	Additional allowance flags as key-value pairs

Hours input

Provide either:

• start_time + end_time + unpaid_break_minutes — the engine calculates hours worked
• total_hours_worked — you provide the total directly

If both are provided, total_hours_worked takes precedence.

Example request

curl -X POST /api/v1/calculate-pay \
  -H "Authorization: Bearer ak_KEY:sk_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "award_code": "MA000009",
    "classification_code": "HI1",
    "employment_type": "full_time",
    "work_date": "2026-03-16",
    "start_time": "09:00",
    "end_time": "17:00",
    "unpaid_break_minutes": 30,
    "is_first_aid_officer": false
  }'

Response

Field	Type	Description
award_code	string	Echo of input award code
classification_code	string	Echo of input classification
employment_type	string	Echo of input employment type
work_date	string	Echo of input date
day_of_week	string	Resolved day name (e.g. Monday, Saturday)
is_public_holiday	boolean	Echo of input
gross_pay	number	Total minimum pay for the shift
ordinary_earnings	number	Ordinary hours earnings
overtime_earnings	number	Overtime earnings
penalty_earnings	number	Penalty rate earnings
allowance_total	number	Total allowances
rate_derivation	object	How the hourly rate was derived from the weekly rate
hours_breakdown	object	How hours were split into ordinary, overtime, and penalty
pay_components	array	Itemised pay components with hours, rate, multiplier, and amount
allowances	array	Itemised allowances
calculation_notes	array	Explanatory notes about the calculation
warnings	array	Engine warnings (e.g. shift exceeds daily maximum)

rate_derivation object

Field	Type	Description
weekly_rate	number	Canonical weekly rate from Schedule B
ordinary_hours_per_week	number	Standard hours per week (e.g. 38)
base_hourly_rate	number	weekly_rate / ordinary_hours_per_week
casual_loading_percent	number or null	Casual loading percentage (e.g. 25.0)
effective_hourly_rate	number	Rate used for calculation (includes casual loading if applicable)
derivation_formula	string	Human-readable formula

pay_components array items

Field	Type	Description
component_type	string	ordinary, overtime_150, overtime_200, penalty, etc.
description	string	Human-readable description
hours	number	Hours for this component
rate	number	Hourly rate applied
multiplier	number	Rate multiplier (e.g. 1.5 for time-and-a-half)
amount	number	Dollar amount for this component
sources	array	Award clause references for traceability

Example response

{
  "award_code": "MA000009",
  "classification_code": "HI1",
  "employment_type": "full_time",
  "work_date": "2026-03-16",
  "day_of_week": "Monday",
  "is_public_holiday": false,
  "gross_pay": 192.22,
  "ordinary_earnings": 192.22,
  "overtime_earnings": 0.0,
  "penalty_earnings": 0.0,
  "allowance_total": 0.0,
  "rate_derivation": {
    "weekly_rate": 973.90,
    "ordinary_hours_per_week": 38.0,
    "base_hourly_rate": 25.6289,
    "effective_hourly_rate": 25.6289,
    "derivation_formula": "973.90 / 38.0 = $25.6289/hr"
  },
  "hours_breakdown": {
    "total_worked_hours": 7.5,
    "unpaid_break_minutes": 30,
    "ordinary_hours": 7.5,
    "overtime_hours_150": 0.0,
    "overtime_hours_200": 0.0
  },
  "pay_components": [
    {
      "component_type": "ordinary",
      "description": "Ordinary hours at base rate",
      "hours": 7.5,
      "rate": 25.6289,
      "multiplier": 1.0,
      "amount": 192.22,
      "sources": [
        {
          "clause_number": "16",
          "clause_title": "Minimum rates",
          "rule_table": "award_base_pay_rates",
          "rule_id": 42
        }
      ]
    }
  ],
  "allowances": [],
  "calculation_notes": [],
  "warnings": []
}

Errors

Status	Cause
400	Invalid request body (missing required fields, invalid values)
404	Award code not found or not calculation-enabled
401	Invalid or missing API credentials
429	Rate limit exceeded