{"openapi":"3.1.0","info":{"title":"Calculate.co.nz API","description":"Free access to New Zealand tax, KiwiSaver, mortgage and property calculations.\nNo sign-up needed to start.\n\n**Anonymous calls are limited to 120 an hour per IP.** That is far more than\na person or an assistant session will ever use, and less than a product needs.\nIf you are building something, request a free key and send it as `X-API-Key`:\nit raises the limit to 5000 an hour and means we can tell you before anything\nchanges. Keys are issued by hand, usually same day. Ask at contact@calculate.co.nz\n\nEvery response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and\n`X-RateLimit-Reset`. Over the limit returns `429` with `Retry-After`.\n\n**Every calculation is a port of the page of the same name on\n[calculate.co.nz](https://www.calculate.co.nz/).** The website is the source of\ntruth: rates come from `paye-data.php`, the same file the site's own calculators\nread, and the test suite fails if the two ever disagree. Rates are reviewed\ntwice monthly against IRD, RBNZ and Stats NZ.\n\n**Fourteen calculators have their own endpoint.** For anything else, call\n`POST /v1/find-calculator` with a plain-language question and it will return the\nright page from the whole site.\n\n**`GET /v1/rates` publishes the underlying New Zealand reference data**: tax\nbrackets, the ACC earner levy and its cap, student loan thresholds, KiwiSaver\nsettings and benefit rates. Each figure carries the date it took effect, where\nit was read from, and when it was last checked against the issuing body, with\n`verified_on` left null rather than guessed where that check has not been done.\nFilter by `review_cycle=annual-1-april` to get everything that moves on 1 April.\n\nThese are the same figures the calculators consume, and an automated harness\ndrives the live pages on the website in a browser and compares their answers to\nthis API. A wrong rate breaks a visible page rather than sitting unnoticed in a\ndata feed.\n\n**Every response carries a `disclaimer`, and it is not boilerplate to strip\nout.** These are estimates under stated assumptions, not financial, tax or legal\nadvice. `POST /v1/paye` also returns an `assumptions` block naming the tax year\nand every rate used, so a stored result can be audited later against the rules\nthat applied on the day.\n\nThe same calculators are available to AI assistants over the Model Context\nProtocol at `https://mcp.calculate.co.nz/mcp`.\n\nQuestions, or something wrong: contact@calculate.co.nz","termsOfService":"https://www.calculate.co.nz/terms.php","contact":{"name":"Calculate.co.nz","url":"https://www.calculate.co.nz/contact.php","email":"contact@calculate.co.nz"},"version":"1.14.0"},"servers":[{"url":"https://api.calculate.co.nz","description":"Production"}],"paths":{"/":{"get":{"tags":["Service"],"summary":"Index of every endpoint","description":"Everything this API offers, in one response.\n\nThe root used to return 404, so anyone who typed the bare hostname was told\nthe API did not exist. This lists the endpoints, points at the human\ndocumentation, and names the MCP endpoint for assistants.","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/health":{"get":{"tags":["Service"],"summary":"Liveness check","description":"Confirm the service is up and see which NZ tax year it is calculating for.\n\nDeliberately cheap and dependency-free: it does not touch the page index, so\nit stays truthful about this service rather than about the website.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/index-status":{"get":{"tags":["Service"],"summary":"State of the search index","description":"Whether the page index behind /v1/find-calculator is loaded and how old.\n\nSeparate from /health on purpose: the index is a soft dependency, and the\nAPI is healthy without it. Folding it into /health would let a website\noutage look like an API outage.","operationId":"index_health_v1_index_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/find-calculator":{"post":{"tags":["Discovery"],"summary":"Find the right calculator, guide or dataset","description":"Search every Calculate.co.nz calculator, guide and dataset by topic.\n\nStart here when there is no dedicated endpoint for what you need, which is\nalmost always: six calculators have their own endpoint and the site has\n2,377. Ask in plain language, the way someone would say it out loud, rather\nthan in keywords. \"how much tax do I pay on my salary\" works better than\n\"tax\", because the ranking reads the whole phrase.\n\nNZ-specific pages outrank generic ones on the same topic. Filter with\n`types` when you only want, say, guides. `score` is comparable within one\nresponse, not between different queries.\n\nThe index is fetched from the website and cached, so the first call after a\nrestart is slower. `GET /v1/index-status` shows whether it is loaded.","operationId":"find_calculator_v1_find_calculator_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindCalculatorRequest"}}},"required":true},"responses":{"200":{"description":"Best matches, highest score first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindCalculatorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/paye":{"post":{"tags":["Calculators"],"summary":"NZ take-home pay after PAYE","description":"Calculate NZ take-home pay for the current tax year.\n\nCovers PAYE income tax across the progressive brackets, the ACC earners\nlevy, KiwiSaver, student loan repayments and the Independent Earner Tax\nCredit. Salary and wages only.\n\nTwo things worth knowing before you display the result:\n\n- `effective_tax_rate` counts income tax and ACC, not KiwiSaver or student\n  loan, so it is not `total_deductions` over gross. KiwiSaver is your money\n  and a student loan repays a debt; neither is tax.\n- `assumptions` names the tax year and every rate used. Store it alongside\n  any saved result, or you will not be able to explain the number after the\n  next Budget.\n\nNot covered: secondary tax codes, ESCT variation, non-resident status,\nWorking for Families, and self-employed income. Those need\n`/v1/find-calculator`.","operationId":"paye_v1_paye_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PAYERequest"}}},"required":true},"responses":{"200":{"description":"Deductions, take-home pay, and the rates used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PAYEResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/gst":{"post":{"tags":["Calculators"],"summary":"Add or remove NZ GST","description":"Add or remove NZ GST (15%) from an amount.\n\n`mode` decides which way round the amount is read. \"add\" treats it as\nGST-exclusive and works out the GST on top; \"remove\" treats it as\nGST-inclusive and works out how much of it is GST. Getting this backwards is\nthe usual source of a wrong answer: removing GST from $115 gives $100, while\ntaking 15% off $115 gives $97.75, which is not the same thing.\n\nEvery response returns all three figures regardless of mode, so the one you\nneed is always present.\n\n`gst_rate` is overridable for historical work: GST was 12.5% before 1 October\n2010. It has been 15% since.","operationId":"gst_v1_gst_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GSTRequest"}}},"required":true},"responses":{"200":{"description":"The amount split into its GST-exclusive, GST and GST-inclusive parts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GSTResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/bmi":{"post":{"tags":["Calculators"],"summary":"Body mass index and healthy weight range","description":"Calculate BMI and classify it into the standard categories.\n\nAlso returns the healthy weight range for the height given, which is\ngenerally more useful than the index itself because it is expressed in\nkilograms rather than an abstract number.\n\nBMI is a population screening tool. It does not distinguish muscle from fat,\nand it is a poor guide for athletes, pregnant people, children and older\nadults. The categories are the WHO adult ones and are not adjusted for\nethnicity, though some NZ guidance uses different cut-offs for Maori,\nPacific and Asian populations.","operationId":"bmi_v1_bmi_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BMIRequest"}}},"required":true},"responses":{"200":{"description":"BMI, its category, and the healthy weight range for that height.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BMIResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/mortgage":{"post":{"tags":["Calculators"],"summary":"Mortgage repayments and lifetime totals","description":"Calculate NZ mortgage repayments and what the loan costs over its term.\n\nUses the standard amortisation formula on a rate compounded monthly, which\nis how NZ lenders quote.\n\nThe fortnightly and weekly figures are the monthly repayment divided by the\naverage number of fortnights (2.174) and weeks (4.348) in a month, matching\ncalculate.co.nz. They are the same annual amount paid more often, NOT an\naccelerated schedule, so they do not shorten the term. Paying half the\nmonthly amount every fortnight is the accelerated version, and it is a\ndifferent calculation.\n\n`annual_interest_rate_pct` is a percentage, so 5.99 rather than 0.0599.\n\nAssumes one constant rate for the whole term. Real NZ mortgages are usually\nfixed in one to five year tranches and re-fixed at whatever the rate is\nthen, so treat a 30 year total as an illustration of the shape rather than a\nforecast.","operationId":"mortgage_v1_mortgage_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MortgageRequest"}}},"required":true},"responses":{"200":{"description":"Repayments at three frequencies, plus total interest over the term.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MortgageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/annual-leave":{"post":{"tags":["Calculators"],"summary":"Annual leave balance projected forward","description":"Project an NZ annual leave balance forward.\n\nAccrues at `holiday_rate_pct` of hours worked. The Holidays Act 2003 minimum\nis four weeks a year, which is the 8% default.\n\nThe same balance comes back in hours, days and weeks, because which one is\nmeaningful depends on the roster: days assume `hours_per_workday` and weeks\nassume `hours_per_workweek`, so a part-timer week of leave is not the same\nnumber of hours as a full-timer one.\n\nThis projects an accrual. It does not calculate what leave is worth in\ndollars, which under the Act depends on ordinary weekly pay versus average\nweekly earnings and is a genuinely harder question.","operationId":"annual_leave_v1_annual_leave_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnualLeaveRequest"}}},"required":true},"responses":{"200":{"description":"Projected balance in hours, days and weeks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnualLeaveResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/fuel-cost":{"post":{"tags":["Calculators"],"summary":"Fuel cost of a trip and of regular driving","description":"Work out what fuel costs, for one trip and for ongoing driving.\n\nConsumption is litres per 100 km, which is how New Zealand quotes it and how\nit is printed on a Gen Vehicle Fuel Economy Label. A LOWER number is a more\nefficient vehicle. Sending miles per gallon or kilometres per litre here\nwill produce a confident and completely wrong answer.\n\nTwo figures answer different questions. `cost_per_100km` depends only on the\nvehicle and the pump price, so it is the one to compare two cars with.\n`cost_per_km` depends on the trip you asked about.\n\nLeave `weekly_km` at zero for a one-off trip. The weekly, monthly and annual\nfigures then come back as zero rather than as an error.\n\n`monthly_cost` is a twelfth of the annual figure, not the weekly cost times\n4.33 and not a calendar month.\n\nFuel only. Not road user charges, which diesel and electric vehicles pay by\nthe kilometre, and not servicing, tyres, insurance or depreciation.","operationId":"fuel_cost_v1_fuel_cost_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelCostRequest"}}},"required":true},"responses":{"200":{"description":"Trip cost, cost per kilometre, and weekly to annual running costs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelCostResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/tax-refund":{"post":{"tags":["Calculators"],"summary":"NZ income tax refund or bill for a year","description":"Estimate a New Zealand tax refund, and show where it comes from.\n\nA refund is simply what was deducted minus what was actually owed. PAYE\ncomes out of each pay as though that pay continued all year, so anything\nthat made the year uneven leaves too much deducted.\n\nThe two usual causes are both broken out in the response. `part_year_over_deducted`\nis what a short year over-deducts, and is often the entire refund.\n`secondary_over_deducted` is what a second job's flat code took beyond what\nthat income actually cost at your marginal rate. Both are already inside\n`refund_or_bill` rather than being additional to it.\n\nGive `paye_deducted` from your payslips or IRD summary for a real answer. If\nyou leave it out, it is estimated from `tax_code` and `months_worked`, which\nneeds nothing from IRD and is correspondingly rougher.\n\nSay whether ACC is inside that figure. Most payslips lump the earner levy in\nwith PAYE, and it is not income tax, so counting it would invent a refund of\nup to $2,741 that does not exist.\n\n`refund_or_bill` is POSITIVE for a refund and NEGATIVE for tax owed. The\nwebsite shows the same number as a positive figure with a separate label, so\nread `is_refund` rather than assuming.\n\nThe donations credit and the student loan square-up are returned but are NOT\nin `refund_or_bill`, because IRD settles them separately.\n\n2024-25 is approximate and says so: the thresholds moved part way through\nthat year, so blended rates apply.\n\nSalary and wages only. Not self-employed or rental income, not Working for\nFamilies, and IRD's own automatic assessment is the figure that counts.","operationId":"tax_refund_v1_tax_refund_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRefundRequest"}}},"required":true},"responses":{"200":{"description":"The refund or amount owing, and every part it is made of.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRefundResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/gpa":{"post":{"tags":["Calculators"],"summary":"Grade point average on the NZ nine point scale","description":"Credit-weighted grade point average for a New Zealand university.\n\nTHE SCALE IS NINE POINTS, NOT FOUR. New Zealand universities grade A+ 9,\nA 8, A- 7, B+ 6, B 5, B- 4, C+ 3, C 2, C- 1, with D and below at zero. A\nGPA of 7.0 here is a strong result, not a broken 4.0 figure, and the two\nscales do not convert by scaling: the bands do not correspond.\n\nIt is credit-weighted, not an average of grades, so an A+ in a 15 credit\npaper does not cancel a C in a 45 credit one. Failed papers still count\ntheir credits at zero points, which is why a fail costs more than expected.\n\nEach paper's contribution comes back so the number can be checked rather\nthan trusted.\n\nUniversities differ on repeated papers, cross-credits and how an award GPA\nis worked out. Use `scale` if yours weights grades differently.","operationId":"gpa_v1_gpa_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GPARequest"}}},"required":true},"responses":{"200":{"description":"The GPA, and each paper's contribution to it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GPAResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/hourly-to-salary":{"post":{"tags":["Calculators"],"summary":"What an hourly rate is worth as a salary","description":"Convert an hourly rate into a salary, before and after tax.\n\nGives gross weekly, fortnightly, monthly and annual, then PAYE, the ACC\nearner levy, KiwiSaver and any student loan, then what is actually left.\n\n`kiwisaver_rate` is a DECIMAL. 0.03 means 3%. Sending 3 would try to\ncontribute three times the salary and is rejected.\n\nTwo figures look similar and answer different questions. `net_weekly`\ndivides by 52 always, so it is what lands each week across a whole year.\n`effective_hourly_after_tax` divides by the hours actually worked, so for a\n40 week year it is higher. That second one is the number to compare a wage\njob against a salaried one.\n\nSalary and wages only, on a primary tax code.","operationId":"hourly_to_salary_v1_hourly_to_salary_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HourlyToSalaryRequest"}}},"required":true},"responses":{"200":{"description":"Gross at each frequency, deductions, and take-home pay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HourlyToSalaryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/work-hours":{"post":{"tags":["Calculators"],"summary":"Total hours from a timesheet, and what they pay","description":"Add up a timesheet and turn it into gross pay.\n\nEach day takes a start, a finish and an unpaid break in minutes. Leave days\noff out of the list rather than sending zeros.\n\nAn overnight shift is handled, not rejected: a finish at or before the start\nis treated as the next day, so 22:00 to 06:00 is eight hours. A break longer\nthan the shift floors the day at zero rather than going negative.\n\nPay is GROSS. For what is left after PAYE, ACC, KiwiSaver and a student loan,\nsend the hourly rate and hours to /v1/hourly-to-salary.\n\nDoes not apply overtime or penal rates, public holiday entitlements, or a\nminimum wage check.","operationId":"work_hours_v1_work_hours_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkHoursRequest"}}},"required":true},"responses":{"200":{"description":"Hours per day, the total, and gross pay at each frequency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkHoursResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/bonus-tax":{"post":{"tags":["Calculators"],"summary":"Tax on a bonus or commission payment","description":"Work out what is left of a New Zealand bonus after tax.\n\nA bonus is an extra emolument. It is NOT taxed at a flat rate, and not at\nyour ordinary rate either. The tax on it is the difference between the tax\non your salary plus the bonus and the tax on your salary alone.\n\nThat is why a bonus can feel over-taxed and still be right. If it straddles\na bracket, part is taxed at the lower rate and part at the higher one, so\nthe effective rate on the bonus lands between them and above your salary's\nrate. `crosses_bracket` says when this has happened.\n\n`annual_salary` matters: the same bonus costs different amounts of tax\ndepending on the salary underneath it.\n\nTwo edges are handled. ACC stops at the earnings cap, so a salary already\nabove it means no levy on the bonus at all. Student loan takes 12% of the\nwhole bonus when the salary is over the repayment threshold, but only of the\npart above the threshold when it is not.\n\nAn employer may deduct at a flat rate through the year and let IRD square it\nup, so a payslip can differ from this while both are correct.","operationId":"bonus_tax_v1_bonus_tax_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BonusTaxRequest"}}},"required":true},"responses":{"200":{"description":"Income tax on the bonus, every other deduction, and what is left.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BonusTaxResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/power-tower":{"post":{"tags":["Calculators"],"summary":"Power tower (tetration), a^^n","description":"Evaluate a power tower, repeated exponentiation.\n\nA tower is evaluated RIGHT TO LEFT: a^^3 is a^(a^a), not (a^a)^a. Those are\ndifferent numbers, and the left-to-right reading is the usual mistake.\n2^^4 is 65,536, not 256.\n\nTowers overflow almost immediately. 3^^4 is 3^7625597484987, a number with\nover three trillion digits, so the height is capped at 10 and anything too\nlarge returns `value: null` with `is_finite: false` rather than a wrong\nnumber or an error.\n\nThis endpoint has no MCP tool on purpose. Every other calculator here\nencodes a New Zealand rule an assistant cannot derive; this is arithmetic a\nmodel does correctly unaided, so a tool would cost tool-selection accuracy\nfor nothing.","operationId":"power_tower_v1_power_tower_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PowerTowerRequest"}}},"required":true},"responses":{"200":{"description":"The tower's value, or a note saying it overflowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PowerTowerResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/parental-leave":{"post":{"tags":["Calculators"],"summary":"NZ paid parental leave payment and shortfall","description":"New Zealand paid parental leave: what arrives, and what is missing.\n\nLEAD WITH THE GAP. The payment is capped, so anyone earning above roughly\n$42,000 receives exactly the cap and the useful figure is `weekly_gap`: how\nmuch less than usual arrives each week, and `total_gap` across the leave.\nQuoting only the payment answers the wrong question for most people.\n\nEligibility is a gate, not a reduction. It needs 26 weeks of work in the\nyear before the due date at 10 or more hours a week. Fail either and the\npayment is zero, and `ineligible_reason` names which test failed and by how\nmuch rather than returning a bare zero.\n\nA self-employed person is paid at least the statutory weekly minimum even\nwhen their income works out lower. An employee gets no such floor.\n\nKiwiSaver contributions during leave are OPT IN. Someone who does nothing\ncontributes nothing for the whole period, employer share included, so\n`kiwisaver_total_over_leave` is what opting in is worth.\n\nThe 26 week entitlement is shareable, and `weeks_available_for_partner` is\nwhat is left for the other parent.","operationId":"parental_leave_v1_parental_leave_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParentalLeaveRequest"}}},"required":true},"responses":{"200":{"description":"Weekly and total payment, and the gap against usual pay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParentalLeaveResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/net-to-gross":{"post":{"tags":["Calculators"],"summary":"The gross salary needed to take home a given amount","description":"Work backwards from a take-home figure to the salary that produces it.\n\nThis is the question behind \"I need $1,200 a week in the hand, what do I\nask for\", and it cannot be answered by scaling: tax is progressive and the\nACC levy is capped, so the gap between gross and net widens as income\nrises. Doubling the target does not double the gross.\n\n`deductions_included` is the field to read first. Take-home means different\nthings to different people, and the same target produces a different gross\ndepending on whether KiwiSaver and a student loan sit inside it. By default\nonly income tax and the ACC levy do, which is what the website page assumes.\n\nThe Independent Earner Tax Credit is not applied. It would lower the gross\nneeded, and eligibility turns on facts this endpoint does not ask for.","operationId":"net_to_gross_v1_net_to_gross_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetToGrossRequest"}}},"required":true},"responses":{"200":{"description":"The gross salary, and every deduction between it and the target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetToGrossResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/final-pay":{"post":{"tags":["Calculators"],"summary":"What is owed on leaving a job, gross","description":"Final pay under the Holidays Act 2003: leave, notice and redundancy.\n\nThe twelve month line decides the whole calculation. Under twelve months of\nservice no leave entitlement has vested, so the Act pays 8% of everything\nearned during the employment. At twelve months and over, unused leave is\npaid out at a daily rate. Someone eleven months in with a leave balance\nshowing in payroll is owed the 8%, not the balance, and getting that branch\nwrong is the usual mistake.\n\n`service` is therefore the input that matters most, and `under12` requires\n`gross_earnings_total` rather than a leave balance.\n\nRead `excludes` before quoting the total. **Ordinary wages for days actually\nworked are not in it** and are paid on top at the usual rate. Everything\nreturned is gross: the leave payout is taxed as an extra pay, which is what\n`/v1/lump-sum-tax` is for.\n\nNew Zealand has no statutory redundancy compensation. Whatever the\nemployment agreement provides is an input here, never a derivation.","operationId":"final_pay_v1_final_pay_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalPayRequest"}}},"required":true},"responses":{"200":{"description":"Leave payout, notice pay and redundancy, with the leave working shown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalPayResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/secondary-tax":{"post":{"tags":["Calculators"],"summary":"Secondary tax code for a second income, and the year-end position","description":"Which secondary tax code a second income takes, and what it really costs.\n\nA secondary code is not a penalty, and almost everyone asking believes it\nis. It approximates the marginal rate the second income attracts on top of\nthe first, so roughly the right amount comes out through the year, and any\nexcess returns in the year-end square-up.\n\nThat is why `year_end_position` is part of the answer rather than an extra.\nThe flat rate matches the true marginal rate only while the second income\nsits inside one bracket; the moment it straddles a boundary the flat rate is\ncharged on all of it and the difference comes back as a refund.\n\nThe rates look punitive because they are not income tax rates. Each carries\nthe 1.75% ACC earner levy inside it, and the SL variants add the 12% student\nloan repayment on top, so 31.75% is 30 plus 1.75. The response takes the\nrate apart into those components rather than making the caller do it.\n\nThe square-up covers these two income sources only. It knows nothing about\nother income, donations, Working for Families or an existing tailored code,\nso treat it as a direction and a rough size.","operationId":"secondary_tax_v1_secondary_tax_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecondaryTaxRequest"}}},"required":true},"responses":{"200":{"description":"The IR330 code, what it deducts, and whether that leaves a bill or a refund.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecondaryTaxResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/pro-rata-salary":{"post":{"tags":["Calculators"],"summary":"A full-time salary scaled to part-time hours","description":"What a full-time salary is worth at fewer hours, gross and after tax.\n\nThe gross part is a proportion, and the useful part is what follows it: the\ntake-home does not scale with the hours, because dropping to half time\ndrops the salary out of the higher brackets. Someone going from full time\nto three days often keeps more than 60% of their take-home, and that is the\nnumber the decision actually turns on.\n\n`hourly_rate` is the full-time salary over full-time hours times 52, which\nis the rate the job pays. Dividing the pro rata salary by the pro rata hours\ngives the same figure.\n\nThe Independent Earner Tax Credit defaults on, because part-time earnings\nare exactly the band where it is worth the most. Turn it off for someone on\na main benefit, Working for Families or NZ Super.","operationId":"pro_rata_salary_v1_pro_rata_salary_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProRataRequest"}}},"required":true},"responses":{"200":{"description":"Gross at the reduced hours, and the take-home the website does not show.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProRataResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/lump-sum-tax":{"post":{"tags":["Calculators"],"summary":"PAYE on a redundancy or lump sum, by IRD's rate table","description":"Tax on a redundancy, retirement payment, bonus or other extra pay.\n\nThis applies IRD's published lump sum rate TABLE: annualised income plus\nthe lump sum selects a single flat rate, and that rate is charged on the\nwhole payment. It is what an employer actually deducts on the day.\n\nThat makes it different from `/v1/bonus-tax`, which computes the same tax\nthe exact way, as tax on salary plus bonus minus tax on salary alone. Both\nare right and they give different answers: the table is the deduction, the\nexact method is roughly where the year-end assessment lands. Use this one to\ncheck a redundancy letter or a payslip.\n\nTwo rules make redundancy different and both are easy to miss. Redundancy\nand retirement payments carry no ACC earner levy, so they always take the\nlower column whatever the income, and no KiwiSaver is deducted from them at\nall. Treating a redundancy like a bonus overstates the deductions twice.\nThe levy also stops for any extra pay once the total passes the ACC liable\nearnings cap, which is why the two columns converge at the top.\n\n`why_that_rate` explains the row that was selected, and\n`annualised_income` shows the one simplification: IRD grosses up the last\nfour weeks of pay, while this takes the annual salary given. They agree for\nsteady pay and part company after a month of heavy overtime or commission.","operationId":"lump_sum_tax_v1_lump_sum_tax_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LumpSumTaxRequest"}}},"required":true},"responses":{"200":{"description":"The flat rate selected, why, and what is left of the payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LumpSumTaxResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/working-for-families":{"post":{"tags":["Calculators"],"summary":"Working for Families entitlement after abatement","description":"A family's Working for Families entitlement for the year.\n\nThis is the endpoint the API exists for. A model can work out a percentage;\nit cannot know that the In-Work Tax Credit is temporarily $7,670 until\n31 March 2027, that it reverts to $5,070, or that the pool abates at\n27.5 cents in the dollar above $44,900.\n\nFamily Tax Credit and In-Work Tax Credit abate TOGETHER against one\nthreshold. Best Start has its own: 21 cents in the dollar above $79,000,\nand it is paid until a child's third birthday, not the first.\n\n**Read `differences_from_website` before comparing this with the page.**\nTwo are deliberate. The website still asks whether the caregiver works 20\nhours a week as a sole parent or 30 combined as a couple, and pays nothing\notherwise; IRD removed that test on 1 July 2020, so this applies the\ncurrent one, which is some income from paid work and no income-tested\nbenefit. And the website pays Best Start in full where this abates it.\n\n`assumptions` returns every rate and threshold used, so a stored answer can\nbe audited later against the rules that applied on the day.\n\nThe Minimum Family Tax Credit is not calculated: it tops a low working\nincome up to a guaranteed net figure, which needs the family's tax position\nrather than its gross income, and IRD works it out separately.","operationId":"working_for_families_v1_working_for_families_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkingForFamiliesRequest"}}},"required":true},"responses":{"200":{"description":"FTC, IWTC and Best Start, each abated by its own rule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkingForFamiliesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/road-user-charges":{"post":{"tags":["Calculators"],"summary":"Road user charges for an EV, diesel or plug-in hybrid","description":"What a light vehicle pays in road user charges over a year.\n\nPetrol vehicles pay for the road invisibly, through excise at the pump.\nDiesels, EVs and plug-in hybrids pay little or no excise and buy road user\ncharges instead, in prepaid 1,000 km blocks, which is why the bill feels\nlike a new tax rather than the same tax collected differently.\n`petrol_equivalent_excise` is there to make that comparison directly.\n\n**The transaction fee is the part a naive calculation misses.** RUC is\nbought in blocks and every purchase carries a fee, so 20,000 km bought in\n1,000 km blocks pays it twenty times. Buying larger blocks is the main\nlever a driver has, and `transactions` and `admin_total` make it visible.\n\nA PETROL plug-in hybrid pays roughly half, because it already pays excise\non the petrol side. A DIESEL plug-in hybrid pays the full rate, because\ndiesel carries no excise. That catches people out.\n\nAn ordinary petrol hybrid pays NO road user charges. It is not exempt: it\npays at the pump like any other petrol vehicle, and the response says so.\n\nLight vehicles 3,500 kg and under only. Heavy vehicle rates run to dozens\nof weight and axle combinations and are not here. `provenance` says which\nfigures are confirmed against NZTA: the rate is, the fees are not.","operationId":"road_user_charges_v1_road_user_charges_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadUserChargesRequest"}}},"required":true},"responses":{"200":{"description":"The annual charge, the transaction fees, and what a petrol driver pays instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadUserChargesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/electricity-cost":{"post":{"tags":["Calculators"],"summary":"Household electricity cost by region and appliance","description":"What a New Zealand household pays for power.\n\nThe arithmetic is kilowatts times hours times rate, which any model does\nunaided. What it cannot know is the New Zealand price data: Wellington pays\n34.61c a unit and Balclutha 48.93c, a 41% spread across one small country,\nfrom MBIE's Quarterly Survey of Domestic Electricity Prices.\n\n**The fixed charge is why a bill is never just usage.** Every connection\ncarries a daily charge whatever you use, so a low user pays a larger share\nof their bill simply for being connected. It is returned separately from\nthe usage cost, because advice that only addresses usage is aiming at part\nof the target. The low fixed charge regulations are being phased out in\nsteps rather than scrapped: capped at $1.80 a day from 1 April 2026 and\nrevoked on 1 April 2027.\n\nbiggest_users is the field to lead with. A heat pump and a hot water\ncylinder dominate almost every bill, and standby power almost never does,\nwhich is the opposite of where most saving advice points.\n\nThe household multiplier is a model, not a measurement: it scales a typical\nappliance profile from 0.60 for one person to 1.30 for five or more. Anyone\nwho knows their own usage should pass appliance_hours instead.","operationId":"electricity_cost_v1_electricity_cost_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ElectricityCostRequest"}}},"required":true},"responses":{"200":{"description":"Daily, monthly and annual cost, with the appliances ranked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ElectricityCostResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/ncea-rank-score":{"post":{"tags":["Calculators"],"summary":"University Entrance rank score, and an indicative GPA","description":"Turn NCEA credits into the two numbers people need from them.\n\nThe asked-for number is a GPA, because a scholarship form or an overseas\nuniversity wants one and NZQA issues none. The widely used weighting is\nExcellence 4, Merit 3, Achieved 2, credit-weighted, and that is returned as\n`indicative_gpa_4_point` with `gpa_is_unofficial` set, because there is no\nauthoritative conversion and pretending otherwise would be the error.\n\nThe number that decides things is `rank_score`. Every New Zealand\nuniversity uses the University Entrance rank score to select for\nlimited-entry programmes: medicine, law, engineering, design. It is the\nBEST 80 credits at Level 3 or above, weighted the same way, capped at 320.\nAlmost nobody asks for it by name, which is why it is returned unasked.\n\n**`credits_ignored` is the field that changes behaviour.** Credits are\ncounted Excellence first, then Merit, then Achieved, until 80 are used, so\na student with 80 Excellence and 40 Achieved scores exactly the same as one\nwith 80 Excellence alone. Collecting more Achieved credits is worth\nnothing; lifting an existing subject to Merit is worth a great deal.\n`next_step` says which case this student is in.\n\nNot Achieved credits are excluded from the rank score entirely and do drag\nthe indicative GPA down, because that is a mean over everything attempted.","operationId":"ncea_rank_score_v1_ncea_rank_score_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NceaRankScoreRequest"}}},"required":true},"responses":{"200":{"description":"The rank score out of 320, the credits that counted, and an unofficial 4-point GPA.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NceaRankScoreResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/vehicle-loan":{"post":{"tags":["Calculators"],"summary":"Vehicle loan repayments and what the interest costs","description":"Repayments on a car loan, and the part that is not the payment.\n\nThe amortisation is ordinary. What makes a vehicle loan worth its own\nendpoint is the context around it. Car finance runs at rates a mortgage\nborrower would not recognise, so `interest_share_of_borrowing` regularly\nlands above 30% over five years, and that single figure does more to inform\na decision than the monthly payment does.\n\nThe term is short, so stretching it barely moves the payment and moves the\ntotal interest a lot. Compare two terms before recommending the longer one.\n\n`fortnightly_equivalent` is the monthly payment converted, because that is\nhow most people are paid. It is NOT a fortnightly amortisation, which would\nclear the loan faster and is a different product; say so if the caller is\ncomparing.\n\nRead `excludes` before quoting the payment as what someone will pay.\nEstablishment fees, PPSR registration, mechanical breakdown insurance and\ndealer add-ons are usually financed too, so a real contract is higher. A\nballoon payment cuts the monthly figure and leaves a lump sum at the end.","operationId":"vehicle_loan_v1_vehicle_loan_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleLoanRequest"}}},"required":true},"responses":{"200":{"description":"Monthly repayment, total interest, and interest as a share of the borrowing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleLoanResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/energy-expenditure":{"post":{"tags":["Calculators"],"summary":"BMR, TDEE, a calorie target and the macros to hit it","description":"Maintenance calories, and the target for losing or gaining.\n\n\"What are my maintenance calories\" and \"what deficit do I need\" are the\nsame calculation from either end, which is why they are one endpoint rather\nthan two that would return identical numbers.\n\n**The formulas disagree, and the response says by how much.** Mifflin-St\nJeor and the revised Harris-Benedict differ by 5 to 10% for the same\nperson, which is often more than the entire deficit someone is trying to\nrun. `formula_spread_kcal` is that gap and `bmr_formula_used` names the one\nthe answer took: Mifflin-St Jeor normally, Katch-McArdle when body fat is\ngiven, because that works from lean mass and is the better estimate.\nQuoting a single number without saying which formula produced it is the\nfailure mode here.\n\nProjections use 7,700 kcal per kilogram of body fat, so a 500 kcal daily\ndeficit is about half a kilogram a week. `weeks_to_target` applies that to\na target weight, and the caveats say plainly that a long projection runs\noptimistic, because metabolic rate falls as weight does.\n\nThese are population formulas, not a measurement of anyone's metabolism.\nThe honest instruction, which is in `caveats`, is to eat at the number for\ntwo to three weeks and adjust from what the scale does.","operationId":"energy_expenditure_v1_energy_expenditure_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnergyExpenditureRequest"}}},"required":true},"responses":{"200":{"description":"All three BMR formulas with their spread, the maintenance figure, and a target for the goal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnergyExpenditureResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/rates":{"get":{"tags":["Reference data"],"summary":"Current New Zealand statutory rates, dated and sourced","description":"Every New Zealand statutory rate this site maintains, with its provenance.\n\nTax brackets, the ACC earner levy and its cap, student loan rate and\nthreshold, KiwiSaver settings, benefit rates and more. Each carries the date\nit took effect, where it was read from, and when it was last checked against\nthe issuing body.\n\n**`verified_on` can be null, and that is deliberate.** A figure recorded but\nnot yet checked against its issuing body says so rather than looking the\nsame as one that was. Hiding the difference would make the whole dataset\nworth less.\n\nFilter with `q` over the id and label, or with `review_cycle` to get\neverything that changes at the same time. `review_cycle=annual-1-april`\nreturns the figures that move on 1 April, which is the query a payroll or\ncompliance team actually has.\n\nThese are the same figures the calculators on calculate.co.nz consume, and\nan automated harness drives those live pages in a browser and compares their\nanswers to this API. A wrong rate breaks a visible page rather than sitting\nunnoticed in a data feed, which is not a claim most rate data can make.","operationId":"rates_v1_rates_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"review_cycle","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Cycle"}}],"responses":{"200":{"description":"The rates, each with its effective date, source and review cycle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RatesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/rates/{rate_id}":{"get":{"tags":["Reference data"],"summary":"One rate by id","description":"A single rate by its stable id, for example `acc-earner-levy`.\n\nIds do not change when a value does, so they are safe to store and to key\non. Call `GET /v1/rates` to see them all.","operationId":"rate_by_id_v1_rates__rate_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"rate_id","in":"path","required":true,"schema":{"type":"string","title":"Rate Id"}}],"responses":{"200":{"description":"The rate, its effective date, source and review cycle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateRecord"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/kiwisaver":{"post":{"tags":["Calculators"],"summary":"KiwiSaver balance projected to retirement","description":"Project a KiwiSaver balance from now until retirement age.\n\nSteps forward month by month, applying employee and employer contributions,\nthe government contribution, investment returns taxed at your PIR, and fund\nfees. Contributions grow with `income_growth_pct`.\n\nThe result breaks the final balance into where it came from: your\ncontributions, your employer contributions after ESCT, voluntary top-ups,\nthe government contribution, investment gains, and fees paid. That breakdown\nis the point of the endpoint; a single final number tells you nothing about\nwhich lever to pull.\n\nRead `final_balance_real_todays_dollars` before `final_balance`. Over thirty\nyears inflation does more to the headline figure than most contribution\ndecisions do, and the real figure is the one comparable to what things cost\nnow.\n\nSet `fund_type` or give `custom_return_pct`. To model de-risking near\nretirement, set `switch_fund_at_age` and `switch_to_fund`.\n\nA projection on constant assumptions, not a forecast. Real returns vary,\nthe rules change, and contribution histories have gaps.","operationId":"kiwisaver_v1_kiwisaver_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KiwiSaverRequest"}}},"required":true},"responses":{"200":{"description":"Projected balance, and where every dollar of it came from.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KiwiSaverResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/fbt":{"post":{"tags":["Calculators"],"summary":"Fringe benefit tax on a vehicle, a low-interest loan or another benefit","description":"Quarterly FBT on one benefit, with the working shown.\n\nThe rate is the easy part. What goes wrong is the taxable value, because\nFBT is charged on a value derived from the asset rather than on what the\nbenefit cost the employer.\n\nFor a vehicle the two methods give very different answers on the same car:\ncost price is 5% a quarter of the GST-inclusive price the employer paid and\nnever falls, while tax book value is 9% a quarter of the written-down value\nwith a floor of $8,333. An old vehicle is usually cheaper on tax book\nvalue; a cheap one can be dearer, because of the floor.\n\nThe days-available divisor is ALWAYS 90 under s RD 29(5)(a) of the Income\nTax Act 2007, never the actual number of days in the quarter. Do not\n\"correct\" it to 91 or 92.\n\nA low-interest loan is taxed on the gap between the prescribed rate and the\nrate charged, so a loan at or above the prescribed rate creates no benefit\nand no FBT.\n\nOn the rate: 63.93% applies to everyone and needs no wash-up. 49.25% is\nlower but available in quarters one to three only, and using it obliges a\nquarter four wash-up that can claw the saving back. Never present the\nalternate rate as simply cheaper; `quarter_four_washup_required` says so\nfor you.\n\n`annual_fbt` is the quarter times four, which only holds if the benefit is\nunchanged all year.","operationId":"fbt_v1_fbt_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FbtRequest"}}},"required":true},"responses":{"200":{"description":"Quarterly taxable value, the rate applied, and the FBT payable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FbtResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/redundancy-entitlement":{"post":{"tags":["Calculators"],"summary":"What is owed on redundancy in New Zealand, mandatory and contractual","description":"Gross entitlements when a role is disestablished.\n\nStart here: NEW ZEALAND HAS NO STATUTORY REDUNDANCY PAY. An employee gets\nredundancy compensation only if their employment agreement provides for it.\nThis is the opposite of the UK and Australian position and it is the most\ncommon error in general advice about NZ redundancy. The default clause is\n\"none\" and `statutory_position` says this in words; pass it on.\n\nWhat IS owed by law is the mandatory side: wages worked and unpaid, annual\nleave not taken, alternative holidays not taken, and the notice period.\n\nTwo totals come back and they answer different questions:\n\n  total_all_in   everything the person receives, the SAME figure whether\n                 notice is worked or paid in lieu. Quote this when someone\n                 asks what they will get.\n  total_package  the final pay only. Quote this when they are asking about\n                 the payslip.\n\nThey differ because notice worked arrives as ordinary salary over those\nweeks rather than as a lump sum. Quoting only the final pay makes payment\nin lieu look better off by a whole notice period, which it is not.\n\nEvery figure is gross. Redundancy compensation is an extra pay taxed at the\nlump sum rate, so use /v1/lump-sum-tax for the tax on it.","operationId":"redundancy_entitlement_v1_redundancy_entitlement_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedundancyEntitlementRequest"}}},"required":true},"responses":{"200":{"description":"Final pay, everything received all in, and the two kept apart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedundancyEntitlementResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/grocery-budget":{"post":{"tags":["Calculators"],"summary":"A weekly grocery budget for a named New Zealand household","description":"What a household should expect to spend on groceries.\n\nBuild the household person by person: a teenager is not a child-sized cost,\nand an average per head hides that. Then diet and region adjust the food\ntotal, and a flat $25 a week covers cleaning products and toiletries unless\nyou turn it off.\n\nAll three spend levels come back every time, and that is the point. A\nsingle figure invites \"that seems high\"; the gap between basic and liberal\nfor the SAME household, in dollars a year, is the number that changes\nanything. On a family of four it is usually several thousand dollars, and\n`annual_gap_basic_to_liberal` puts it in one place.\n\nBe straight about what these figures are. They are indicative planning\nfigures used by the website calculator, not a measured survey result and\nnot a benchmark to hold anyone to. Someone who wants measured New Zealand\ndata wants the Household Economic Survey pages instead, so say so rather\nthan presenting these as official.","operationId":"grocery_budget_v1_grocery_budget_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroceryBudgetRequest"}}},"required":true},"responses":{"200":{"description":"Weekly, monthly and annual budgets, with all three spend levels.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroceryBudgetResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/contractor-vs-employee":{"post":{"tags":["Calculators"],"summary":"Contracting against salaried employment, on what you actually keep","description":"Compare a contract rate with a salary honestly.\n\nAlmost everyone compares the two headline numbers as though they were the\nsame kind of number. They are not. An employee's package includes things a\ncontractor funds out of the rate:\n\n  - Employer KiwiSaver, at least 3.5% from 1 April 2026, less ESCT. A\n    contractor gets no match, so the same percentage costs them all of it.\n  - Annual leave, ten sick days and eleven public holidays. Around 45 of\n    the 260 working days in a year.\n  - The ACC work levy, which an employer pays and a contractor does not.\n\nSo two comparisons come back. `cash_difference` is take-home against\ntake-home, and it is the one that flatters contracting because it ignores\nall of the above. `package_difference` is the honest one. It is common for\na contract to be well ahead on cash and behind on package, and if you quote\nonly the first you have given bad advice.\n\n`breakeven_contract_income` answers the question people actually have,\nwhich is what they need to charge. It is solved by bisection rather than\nscaled linearly, because the tax ladder is piecewise and a linear guess is\nwrong at every bracket edge.\n\n`annual_contract_income` is the year's total invoicing, NOT a rate to be\nmultiplied up. `billable_weeks` only expresses the implied rate.\n\nGST is excluded throughout: over $60,000 of turnover registration is\ncompulsory, but GST is collected and passed on rather than earned. Also\nabsent, and worth saying out loud: notice periods and personal grievance\nrights have real value and no dollar figure.","operationId":"contractor_vs_employee_v1_contractor_vs_employee_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractorVsEmployeeRequest"}}},"required":true},"responses":{"200":{"description":"Both sides costed, the difference on cash and on package, and the breakeven rate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractorVsEmployeeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}}},"components":{"schemas":{"AnnualLeaveRequest":{"properties":{"current_balance":{"type":"number","minimum":0.0,"title":"Current Balance","description":"Existing balance"},"current_balance_unit":{"type":"string","enum":["hours","days"],"title":"Current Balance Unit","description":"Unit that current_balance is expressed in.","default":"hours"},"hours_per_workday":{"type":"number","maximum":24.0,"exclusiveMinimum":0.0,"title":"Hours Per Workday","description":"Hours in a normal working day, used to convert days to hours.","default":8},"holiday_rate_pct":{"type":"number","minimum":0.0,"title":"Holiday Rate Pct","description":"Accrual rate as a percentage of hours worked. The Holidays Act 2003 minimum of four weeks a year is 8%.","default":8},"hours_per_workweek":{"type":"number","exclusiveMinimum":0.0,"title":"Hours Per Workweek","description":"Hours worked in a normal week.","default":40},"future_period":{"type":"number","minimum":0.0,"title":"Future Period","description":"How far ahead to project, in future_period_unit.","default":12},"future_period_unit":{"type":"string","enum":["weeks","months","years"],"title":"Future Period Unit","description":"Unit that future_period is expressed in.","default":"months"}},"type":"object","required":["current_balance"],"title":"AnnualLeaveRequest","example":{"current_balance":40,"current_balance_unit":"hours","future_period":12,"future_period_unit":"months","holiday_rate_pct":8,"hours_per_workday":8,"hours_per_workweek":40}},"AnnualLeaveResponse":{"properties":{"result":{"$ref":"#/components/schemas/AnnualLeaveResult","description":"Projected balance in three units."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"AnnualLeaveResponse","example":{"disclaimer":"Estimate only. Actual leave accrual depends on your employment agreement and the Holidays Act 2003. Not legal advice.","result":{"hours_accrued_per_week":3.2,"inputs":{"current_balance":40.0,"current_balance_unit":"hours","future_period":12.0,"future_period_unit":"months","holiday_rate_pct":8.0,"hours_per_workday":8.0,"hours_per_workweek":40.0},"projected_balance_days":25.86,"projected_balance_hours":206.86,"projected_balance_weeks":5.17}}},"AnnualLeaveResult":{"properties":{"hours_accrued_per_week":{"type":"number","title":"Hours Accrued Per Week","description":"Leave earned each week at this rate and workweek."},"projected_balance_hours":{"type":"number","title":"Projected Balance Hours","description":"Balance at the end of the period, in hours."},"projected_balance_days":{"type":"number","title":"Projected Balance Days","description":"The same balance in days, at hours_per_workday."},"projected_balance_weeks":{"type":"number","title":"Projected Balance Weeks","description":"The same balance in weeks, at hours_per_workweek."},"inputs":{"additionalProperties":true,"type":"object","title":"Inputs","description":"The inputs used, echoed back with defaults filled in."}},"type":"object","required":["hours_accrued_per_week","projected_balance_hours","projected_balance_days","projected_balance_weeks","inputs"],"title":"AnnualLeaveResult"},"Assumptions":{"properties":{"tax_year":{"type":"string","title":"Tax Year","description":"NZ tax year the rules are taken from, e.g. 2026/27."},"kiwisaver_min_rate":{"type":"number","title":"Kiwisaver Min Rate","description":"Minimum employee contribution rate, as a decimal."},"acc_levy_rate":{"type":"number","title":"Acc Levy Rate","description":"ACC earners' levy rate, as a decimal."},"student_loan_threshold":{"type":"number","title":"Student Loan Threshold","description":"Annual income above which student loan repayments start, in NZD."},"student_loan_rate":{"type":"number","title":"Student Loan Rate","description":"Repayment rate on income above the threshold, as a decimal."}},"type":"object","required":["tax_year","kiwisaver_min_rate","acc_levy_rate","student_loan_threshold","student_loan_rate"],"title":"Assumptions"},"BMIRequest":{"properties":{"weight_kg":{"type":"number","exclusiveMinimum":0.0,"title":"Weight Kg","description":"Weight in kilograms"},"height_m":{"type":"number","maximum":3.0,"exclusiveMinimum":0.0,"title":"Height M","description":"Height in metres"}},"type":"object","required":["weight_kg","height_m"],"title":"BMIRequest","example":{"height_m":1.8,"weight_kg":80.0}},"BMIResponse":{"properties":{"result":{"$ref":"#/components/schemas/BMIResult","description":"BMI, category and healthy weight range."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"BMIResponse","example":{"disclaimer":"BMI is a screening tool, not a diagnosis. It does not distinguish muscle mass from fat. Consult a health professional for personalised advice.","result":{"bmi":24.69,"category":"Healthy weight","healthy_weight_max_kg":80.68,"healthy_weight_min_kg":59.94,"height_m":1.8,"weight_kg":80.0}}},"BMIResult":{"properties":{"bmi":{"type":"number","title":"Bmi","description":"Body mass index, weight divided by height squared."},"category":{"type":"string","title":"Category","description":"Standard classification: Underweight, Healthy weight, Overweight or Obese."},"weight_kg":{"type":"number","title":"Weight Kg","description":"Weight you sent, in kilograms."},"height_m":{"type":"number","title":"Height M","description":"Height you sent, in metres."},"healthy_weight_min_kg":{"type":"number","title":"Healthy Weight Min Kg","description":"Lightest weight in the healthy BMI band at this height."},"healthy_weight_max_kg":{"type":"number","title":"Healthy Weight Max Kg","description":"Heaviest weight in the healthy BMI band at this height."}},"type":"object","required":["bmi","category","weight_kg","height_m","healthy_weight_min_kg","healthy_weight_max_kg"],"title":"BMIResult"},"BonusTaxRequest":{"properties":{"bonus_amount":{"type":"number","minimum":0.0,"title":"Bonus Amount","description":"Gross bonus or commission, in NZD."},"annual_salary":{"type":"number","minimum":0.0,"title":"Annual Salary","description":"Regular annual salary, EXCLUDING the bonus. This decides which tax brackets the bonus falls into, so the answer depends on it."},"kiwisaver_rate":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Kiwisaver Rate","description":"Employee contribution as a DECIMAL: 0.03 for 3%.","default":0.03},"has_student_loan":{"type":"boolean","title":"Has Student Loan","description":"Whether repayments are deducted.","default":false}},"type":"object","required":["bonus_amount","annual_salary"],"title":"BonusTaxRequest","example":{"annual_salary":75000,"bonus_amount":10000,"has_student_loan":false,"kiwisaver_rate":0.03}},"BonusTaxResponse":{"properties":{"result":{"$ref":"#/components/schemas/BonusTaxResult","description":"Tax and deductions on the bonus."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"BonusTaxResponse","example":{"disclaimer":"Estimate only. Employers may deduct a bonus at a flat rate through the year and square it up at assessment, so a payslip can differ from this while both are correct. Not financial or tax advice.","result":{"acc_levy":175.0,"annual_salary":75000.0,"bonus_amount":10000.0,"crosses_bracket":true,"effective_tax_rate_on_bonus":32.07,"income_tax_on_bonus":3207.0,"kiwisaver":300.0,"net_bonus":6318.0,"student_loan":0.0,"tax_on_salary_alone":14720.5,"tax_on_salary_plus_bonus":17927.5,"top_bracket_reached":33.0,"total_deductions":3682.0}}},"BonusTaxResult":{"properties":{"bonus_amount":{"type":"number","title":"Bonus Amount","description":"Gross bonus."},"annual_salary":{"type":"number","title":"Annual Salary","description":"Salary the bonus sits on top of."},"tax_on_salary_alone":{"type":"number","title":"Tax On Salary Alone","description":"Annual income tax on the salary by itself."},"tax_on_salary_plus_bonus":{"type":"number","title":"Tax On Salary Plus Bonus","description":"Annual income tax on both together."},"income_tax_on_bonus":{"type":"number","title":"Income Tax On Bonus","description":"The difference between those two, which is what the bonus actually costs in tax. IRD calls this the extra emolument method."},"effective_tax_rate_on_bonus":{"type":"number","title":"Effective Tax Rate On Bonus","description":"Tax on the bonus as a percentage of it. Higher than the rate on the salary whenever the bonus crosses a bracket, which is normal and not an error."},"acc_levy":{"type":"number","title":"Acc Levy","description":"ACC earner levy on the bonus. Zero when the salary alone already exceeds the liable earnings cap, and charged only on the part below the cap when the bonus crosses it."},"kiwisaver":{"type":"number","title":"Kiwisaver","description":"Employee KiwiSaver contribution on the bonus."},"student_loan":{"type":"number","title":"Student Loan","description":"Repayment on the bonus. The whole bonus when the salary is already over the threshold, only the part above it when the salary is not."},"total_deductions":{"type":"number","title":"Total Deductions","description":"Everything taken off the bonus."},"net_bonus":{"type":"number","title":"Net Bonus","description":"What actually reaches the employee."},"crosses_bracket":{"type":"boolean","title":"Crosses Bracket","description":"True when the bonus straddles a tax bracket."},"top_bracket_reached":{"type":"number","title":"Top Bracket Reached","description":"The marginal rate the top of the bonus reaches, as a percentage."}},"type":"object","required":["bonus_amount","annual_salary","tax_on_salary_alone","tax_on_salary_plus_bonus","income_tax_on_bonus","effective_tax_rate_on_bonus","acc_levy","kiwisaver","student_loan","total_deductions","net_bonus","crosses_bracket","top_bracket_reached"],"title":"BonusTaxResult"},"ContractorVsEmployeeRequest":{"properties":{"annual_gross_salary":{"type":"number","minimum":0.0,"title":"Annual Gross Salary","description":"The salaried offer, gross."},"annual_contract_income":{"type":"number","minimum":0.0,"title":"Annual Contract Income","description":"Total expected to invoice across the year, GST exclusive. This is the year's total, not a rate: it is NOT scaled by billable_weeks."},"annual_business_expenses":{"type":"number","minimum":0.0,"title":"Annual Business Expenses","description":"Deductible business expenses for the year.","default":0.0},"billable_weeks":{"type":"number","maximum":52.0,"exclusiveMinimum":0.0,"title":"Billable Weeks","description":"Weeks expected to bill. Used only to express the implied rate.","default":46.0},"acc_work_levy_pct":{"type":"number","maximum":20.0,"minimum":0.0,"title":"Acc Work Levy Pct","description":"ACC work levy as a percentage of liable income. A contractor pays this; an employee's employer does. Varies a lot by industry.","default":0.7},"employer_kiwisaver_rate_pct":{"type":"number","minimum":0.0,"title":"Employer Kiwisaver Rate Pct","description":"Employer contribution. Minimum 3.5% from 1 April 2026.","default":3.5},"own_kiwisaver_rate_pct":{"type":"number","minimum":0.0,"title":"Own Kiwisaver Rate Pct","description":"The person's own contribution rate, applied to both sides.","default":3.5},"annual_leave_days":{"type":"number","maximum":60.0,"minimum":0.0,"title":"Annual Leave Days","description":"Annual leave in the employment offer.","default":20.0},"has_student_loan":{"type":"boolean","title":"Has Student Loan","description":"Applies to both sides.","default":false},"claim_ietc":{"type":"boolean","title":"Claim Ietc","description":"Whether the independent earner tax credit is claimable.","default":true}},"type":"object","required":["annual_gross_salary","annual_contract_income"],"title":"ContractorVsEmployeeRequest","example":{"acc_work_levy_pct":0.7,"annual_business_expenses":8000,"annual_contract_income":130000,"annual_gross_salary":100000,"annual_leave_days":20,"billable_weeks":46,"claim_ietc":true,"employer_kiwisaver_rate_pct":3.5,"has_student_loan":false,"own_kiwisaver_rate_pct":3.5}},"ContractorVsEmployeeResponse":{"properties":{"result":{"$ref":"#/components/schemas/ContractorVsEmployeeResult","description":"Both sides costed, and the breakeven between them."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"ContractorVsEmployeeResponse","example":{"disclaimer":"A comparison of take-home value on current NZ tax settings. It excludes GST, provisional tax timing, insurance and accountancy costs, and puts no value on employment protections. Not tax or employment advice.","result":{"better_on_cash":"contractor","better_on_package":"employee","breakeven_contract_income":138817.74,"business_expenses":8000.0,"cash_difference":12731.0,"contract_income":130000.0,"contractor_acc_earners_levy":2135.0,"contractor_acc_work_levy":854.0,"contractor_billable_weeks":46.0,"contractor_ietc":0.0,"contractor_implied_daily_rate":565.22,"contractor_implied_weekly_rate":2826.09,"contractor_income_tax":30137.5,"contractor_kiwisaver_own":4270.0,"contractor_net_cash":84603.5,"contractor_student_loan":0.0,"contractor_taxable_income":122000.0,"employee_acc_levy":1750.0,"employee_ietc":0.0,"employee_kiwisaver_own":3500.0,"employee_leave_value":15769.23,"employee_net_cash":71872.5,"employee_package_value":89986.73,"employee_paye":22877.5,"employee_salary":100000.0,"employee_student_loan":0.0,"employer_kiwisaver_esct":1155.0,"employer_kiwisaver_gross":3500.0,"employer_kiwisaver_net":2345.0,"excludes":["GST","Provisional tax timing and use of money interest","ACC CoverPlus Extra, income protection and liability insurance","Accountancy and administration costs","The risk of an invoice not being paid","Notice periods and personal grievance rights, which have real value and no dollar figure"],"notes":["package_difference is the comparison that matters. cash_difference ignores employer KiwiSaver and paid leave, which is exactly the mistake that makes contracting look better than it is.","The employee's leave is worth $15,769: 20 days annual leave plus 10 sick days and 11 public holidays, at their daily rate.","breakeven_contract_income is what you would need to invoice, before expenses, to match the salaried package. Below $138,818 the salary is ahead.","GST is excluded. Over $60,000 of turnover a contractor must register, but GST is collected and passed on, not earned.","The implied rate assumes 46 billable weeks. The contract income is taken as the year's total and is not scaled by it."],"package_difference":-5383.23}}},"ContractorVsEmployeeResult":{"properties":{"employee_salary":{"type":"number","title":"Employee Salary","description":"Salary as given."},"employee_paye":{"type":"number","title":"Employee Paye","description":"PAYE on the salary."},"employee_acc_levy":{"type":"number","title":"Employee Acc Levy","description":"ACC earners levy on the salary."},"employee_student_loan":{"type":"number","title":"Employee Student Loan","description":"Student loan deductions."},"employee_ietc":{"type":"number","title":"Employee Ietc","description":"Independent earner tax credit."},"employee_kiwisaver_own":{"type":"number","title":"Employee Kiwisaver Own","description":"Their own KiwiSaver contribution."},"employer_kiwisaver_gross":{"type":"number","title":"Employer Kiwisaver Gross","description":"Employer contribution before ESCT."},"employer_kiwisaver_esct":{"type":"number","title":"Employer Kiwisaver Esct","description":"ESCT deducted from it."},"employer_kiwisaver_net":{"type":"number","title":"Employer Kiwisaver Net","description":"What actually reaches the fund. This is the part a contractor loses."},"employee_net_cash":{"type":"number","title":"Employee Net Cash","description":"Take-home pay."},"employee_leave_value":{"type":"number","title":"Employee Leave Value","description":"Annual leave, ten sick days and eleven public holidays at the daily rate. Around 45 of 260 working days."},"employee_package_value":{"type":"number","title":"Employee Package Value","description":"Cash plus employer KiwiSaver plus paid leave. The number to compare."},"contract_income":{"type":"number","title":"Contract Income","description":"Contract income as given."},"business_expenses":{"type":"number","title":"Business Expenses","description":"Expenses as given."},"contractor_taxable_income":{"type":"number","title":"Contractor Taxable Income","description":"Income less expenses."},"contractor_income_tax":{"type":"number","title":"Contractor Income Tax","description":"Income tax on the taxable amount."},"contractor_acc_earners_levy":{"type":"number","title":"Contractor Acc Earners Levy","description":"ACC earners levy."},"contractor_acc_work_levy":{"type":"number","title":"Contractor Acc Work Levy","description":"ACC work levy, which an employee does not pay."},"contractor_student_loan":{"type":"number","title":"Contractor Student Loan","description":"Student loan deductions."},"contractor_ietc":{"type":"number","title":"Contractor Ietc","description":"Independent earner tax credit."},"contractor_kiwisaver_own":{"type":"number","title":"Contractor Kiwisaver Own","description":"Their own contribution, with no employer match against it."},"contractor_net_cash":{"type":"number","title":"Contractor Net Cash","description":"What the contractor keeps."},"contractor_billable_weeks":{"type":"number","title":"Contractor Billable Weeks","description":"Billable weeks as given."},"contractor_implied_weekly_rate":{"type":"number","title":"Contractor Implied Weekly Rate","description":"Contract income divided by billable weeks."},"contractor_implied_daily_rate":{"type":"number","title":"Contractor Implied Daily Rate","description":"Contract income divided by billable days."},"cash_difference":{"type":"number","title":"Cash Difference","description":"Contractor net cash less employee net cash. Positive favours contracting. This is the comparison that flatters contracting, because it ignores employer KiwiSaver and paid leave."},"package_difference":{"type":"number","title":"Package Difference","description":"Contractor net cash less the employee's full package. Positive favours contracting. This is the honest comparison."},"better_on_cash":{"type":"string","title":"Better On Cash","description":"'contractor' or 'employee'."},"better_on_package":{"type":"string","title":"Better On Package","description":"'contractor' or 'employee'."},"breakeven_contract_income":{"type":"number","title":"Breakeven Contract Income","description":"The contract income, before expenses, at which contracting matches the salaried package. Answers 'what do I need to charge'."},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"What drove the result."},"excludes":{"items":{"type":"string"},"type":"array","title":"Excludes","description":"What this deliberately does not model."}},"type":"object","required":["employee_salary","employee_paye","employee_acc_levy","employee_student_loan","employee_ietc","employee_kiwisaver_own","employer_kiwisaver_gross","employer_kiwisaver_esct","employer_kiwisaver_net","employee_net_cash","employee_leave_value","employee_package_value","contract_income","business_expenses","contractor_taxable_income","contractor_income_tax","contractor_acc_earners_levy","contractor_acc_work_levy","contractor_student_loan","contractor_ietc","contractor_kiwisaver_own","contractor_net_cash","contractor_billable_weeks","contractor_implied_weekly_rate","contractor_implied_daily_rate","cash_difference","package_difference","better_on_cash","better_on_package","breakeven_contract_income","notes","excludes"],"title":"ContractorVsEmployeeResult"},"ElectricityApplianceRow":{"properties":{"name":{"type":"string","title":"Name","description":"Appliance."},"watts":{"type":"integer","title":"Watts","description":"Rated power draw."},"hours_per_day":{"type":"number","title":"Hours Per Day","description":"Hours run a day."},"kwh_per_day":{"type":"number","title":"Kwh Per Day","description":"Energy used a day."},"daily_cost":{"type":"number","title":"Daily Cost","description":"What it costs a day at your rate."},"annual_cost":{"type":"number","title":"Annual Cost","description":"What it costs a year."}},"type":"object","required":["name","watts","hours_per_day","kwh_per_day","daily_cost","annual_cost"],"title":"ElectricityApplianceRow"},"ElectricityCostRequest":{"properties":{"region":{"type":"string","title":"Region","description":"One of the MBIE survey towns, or \"nz average\". Case insensitive. The spread is wide: Wellington 34.61c against Balclutha 48.93c.","default":"nz average"},"household_size":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Household Size","description":"1 to 5, where 5 means five or more. Scales the appliance profile.","default":3},"daily_fixed_charge":{"type":"number","minimum":0.0,"title":"Daily Fixed Charge","description":"The daily connection charge in DOLLARS, from your bill. Typically $0.30 to $2.50. Charged whatever you use.","default":1.5},"custom_rate_cents":{"type":"number","minimum":0.0,"title":"Custom Rate Cents","description":"Your own rate in cents per kWh including GST. Overrides the region.","default":0.0},"appliance_hours":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Appliance Hours","description":"Override any appliance's daily hours, keyed by heat_pump, hot_water, oven, clothes_dryer, ev_charger, fridge_freezer, dishwasher, washing_machine, stovetop, induction_cooktop, tv, computer, lights, electric_heater."}},"type":"object","title":"ElectricityCostRequest","example":{"custom_rate_cents":0.0,"daily_fixed_charge":1.5,"household_size":3,"region":"auckland"}},"ElectricityCostResponse":{"properties":{"result":{"$ref":"#/components/schemas/ElectricityCostResult","description":"Cost, by appliance and in total."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"ElectricityCostResponse","example":{"disclaimer":"Indicative. Regional rates are MBIE QSDEP February 2026 for a modelled household on a standard tariff; actual cost depends on your retailer, plan, tariff structure and usage. Compare plans at powerswitch.org.nz.","result":{"annual_at_nz_average":5038.76,"annual_kwh":11428.15,"annual_total":4947.34,"appliances":[{"annual_cost":1264.73,"daily_cost":3.47,"hours_per_day":6.0,"kwh_per_day":9.0,"name":"Heat pump","watts":1500},{"annual_cost":1264.73,"daily_cost":3.47,"hours_per_day":3.0,"kwh_per_day":9.0,"name":"Hot water cylinder","watts":3000},{"annual_cost":281.05,"daily_cost":0.77,"hours_per_day":1.0,"kwh_per_day":2.0,"name":"Oven","watts":2000},{"annual_cost":337.26,"daily_cost":0.92,"hours_per_day":1.0,"kwh_per_day":2.4,"name":"Clothes dryer","watts":2400},{"annual_cost":0.0,"daily_cost":0.0,"hours_per_day":0.0,"kwh_per_day":0.0,"name":"EV charger (7kW)","watts":7000},{"annual_cost":505.89,"daily_cost":1.39,"hours_per_day":24.0,"kwh_per_day":3.6,"name":"Fridge/freezer","watts":150},{"annual_cost":252.95,"daily_cost":0.69,"hours_per_day":1.0,"kwh_per_day":1.8,"name":"Dishwasher","watts":1800},{"annual_cost":70.26,"daily_cost":0.19,"hours_per_day":1.0,"kwh_per_day":0.5,"name":"Washing machine","watts":500},{"annual_cost":105.39,"daily_cost":0.29,"hours_per_day":0.5,"kwh_per_day":0.75,"name":"Stovetop/hob","watts":1500},{"annual_cost":140.53,"daily_cost":0.39,"hours_per_day":0.5,"kwh_per_day":1.0,"name":"Induction cooktop","watts":2000},{"annual_cost":56.21,"daily_cost":0.15,"hours_per_day":4.0,"kwh_per_day":0.4,"name":"TV","watts":100},{"annual_cost":50.59,"daily_cost":0.14,"hours_per_day":6.0,"kwh_per_day":0.36,"name":"Computer/laptop","watts":60},{"annual_cost":70.26,"daily_cost":0.19,"hours_per_day":5.0,"kwh_per_day":0.5,"name":"LED lights (10 bulbs)","watts":100},{"annual_cost":0.0,"daily_cost":0.0,"hours_per_day":0.0,"kwh_per_day":0.0,"name":"Electric heater (fan)","watts":2000}],"biggest_users":["Heat pump","Hot water cylinder","Fridge/freezer"],"cheapest_region":{"name":"wellington","rate":34.61},"daily_fixed_charge":1.5,"daily_kwh":31.31,"daily_kwh_before_multiplier":31.31,"daily_total":13.55,"daily_usage_cost":12.05,"household_multiplier":1.0,"household_size":3,"monthly_total":412.05,"most_expensive_region":{"name":"balclutha","rate":48.93},"note":"The daily fixed charge is separate from usage, so a low user pays a larger share of their bill simply for being connected. Compare a low fixed charge plan if the household uses under 8,000 kWh a year: those regulations are capped at $1.80 a day from 1 April 2026 and are revoked on 1 April 2027.","nz_average_rate":39.3,"rate_cents_per_kwh":38.5,"rate_source":"MBIE QSDEP, February 2026, auckland, including GST","region":"auckland","regions_compared":24,"saving_against_most_expensive":1191.96}}},"ElectricityCostResult":{"properties":{"region":{"type":"string","title":"Region","description":"Region used."},"rate_cents_per_kwh":{"type":"number","title":"Rate Cents Per Kwh","description":"Unit rate applied, including GST."},"rate_source":{"type":"string","title":"Rate Source","description":"Where that rate came from."},"household_size":{"type":"integer","title":"Household Size","description":"People in the household."},"household_multiplier":{"type":"number","title":"Household Multiplier","description":"Scale applied to the appliance profile."},"daily_kwh_before_multiplier":{"type":"number","title":"Daily Kwh Before Multiplier","description":"Raw appliance total."},"daily_kwh":{"type":"number","title":"Daily Kwh","description":"After the household multiplier."},"daily_usage_cost":{"type":"number","title":"Daily Usage Cost","description":"Energy cost a day."},"daily_fixed_charge":{"type":"number","title":"Daily Fixed Charge","description":"The connection charge, kept separate because advice that only addresses usage is aiming at part of the bill."},"daily_total":{"type":"number","title":"Daily Total","description":"Usage plus fixed charge."},"monthly_total":{"type":"number","title":"Monthly Total","description":"Daily total over 30.4 days."},"annual_total":{"type":"number","title":"Annual Total","description":"Daily total over 365 days."},"annual_kwh":{"type":"number","title":"Annual Kwh","description":"Energy used in a year."},"appliances":{"items":{"$ref":"#/components/schemas/ElectricityApplianceRow"},"type":"array","title":"Appliances","description":"Every appliance with its own cost."},"biggest_users":{"items":{"type":"string"},"type":"array","title":"Biggest Users","description":"The three costing the most a year, which is where any saving is."},"nz_average_rate":{"type":"number","title":"Nz Average Rate","description":"MBIE's national figure."},"annual_at_nz_average":{"type":"number","title":"Annual At Nz Average","description":"The same household at the national rate."},"cheapest_region":{"additionalProperties":true,"type":"object","title":"Cheapest Region","description":"Cheapest surveyed town and its rate."},"most_expensive_region":{"additionalProperties":true,"type":"object","title":"Most Expensive Region","description":"Dearest surveyed town and its rate."},"regions_compared":{"type":"integer","title":"Regions Compared","description":"How many real towns the comparison covered. MBIE national average is excluded, since it is a figure rather than a place."},"saving_against_most_expensive":{"type":"number","title":"Saving Against Most Expensive","description":"Annual difference against the dearest town."},"note":{"type":"string","title":"Note","description":"What the fixed charge means for a low user."}},"type":"object","required":["region","rate_cents_per_kwh","rate_source","household_size","household_multiplier","daily_kwh_before_multiplier","daily_kwh","daily_usage_cost","daily_fixed_charge","daily_total","monthly_total","annual_total","annual_kwh","appliances","biggest_users","nz_average_rate","annual_at_nz_average","cheapest_region","most_expensive_region","regions_compared","saving_against_most_expensive","note"],"title":"ElectricityCostResult"},"EnergyExpenditureRequest":{"properties":{"sex":{"type":"string","title":"Sex","description":"\"male\" or \"female\". It changes the formula constant."},"age":{"type":"integer","maximum":120.0,"exclusiveMinimum":0.0,"title":"Age","description":"Age in years. The formulas are validated roughly 18 to 75."},"weight_kg":{"type":"number","exclusiveMinimum":0.0,"title":"Weight Kg","description":"Body weight in kilograms."},"height_cm":{"type":"number","exclusiveMinimum":0.0,"title":"Height Cm","description":"Height in centimetres."},"activity_level":{"type":"string","title":"Activity Level","description":"sedentary, light, moderate, very_active or extra_active. Most people overestimate this; one level lower than it feels is usually closer.","default":"moderate"},"goal":{"type":"string","title":"Goal","description":"lose, maintain or gain.","default":"maintain"},"body_fat_pct":{"type":"number","exclusiveMaximum":100.0,"minimum":0.0,"title":"Body Fat Pct","description":"Optional. When known, Katch-McArdle is computed and used as the primary, because it works from lean mass.","default":0.0},"target_weight_kg":{"type":"number","minimum":0.0,"title":"Target Weight Kg","description":"Optional. Produces a timeline at the chosen offset.","default":0.0}},"type":"object","required":["sex","age","weight_kg","height_cm"],"title":"EnergyExpenditureRequest","example":{"activity_level":"moderate","age":35,"body_fat_pct":0.0,"goal":"lose","height_cm":180,"sex":"male","target_weight_kg":78,"weight_kg":85}},"EnergyExpenditureResponse":{"properties":{"result":{"$ref":"#/components/schemas/EnergyExpenditureResult","description":"BMR, TDEE, target and macros."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"EnergyExpenditureResponse","example":{"disclaimer":"Estimates from population formulas, not a measurement of your metabolism. The formulas disagree by 5 to 10%, so the one used is named. Adjust from what your weight actually does over two to three weeks. Not medical advice.","result":{"activity_description":"exercise 3 to 5 days a week","activity_level":"moderate","activity_multiplier":1.55,"age":35,"bmr":1805.0,"bmr_formula_used":"Mifflin-St Jeor, the better validated of the two that need no body fat figure","bmr_harris_benedict":1892.0,"bmr_katch_mcardle":0.0,"bmr_mifflin_st_jeor":1805.0,"carbs_g":244.0,"carbs_kcal":974.0,"caveats":["These are population formulas, not a measurement of your metabolism. Eat at the number for two to three weeks and adjust from what the scale actually does.","The three formulas disagree by 87.0 kcal for this person. That gap is larger than many deficits, which is why the one used is named.","The timeline assumes a constant rate. Metabolic rate falls as weight does, so a long projection runs optimistic."],"daily_calorie_target":2298.0,"daily_offset":-500.0,"fat_g":71.0,"fat_kcal":643.0,"formula_spread_kcal":87.0,"goal":"lose","height_cm":180.0,"minimum_fat_applied":false,"projected_weekly_change_kg":-0.45,"protein_g":170.0,"protein_kcal":680.0,"sex":"male","tdee":2798.0,"weeks_to_target":15.4,"weight_kg":85.0}}},"EnergyExpenditureResult":{"properties":{"sex":{"type":"string","title":"Sex","description":"Sex as given."},"age":{"type":"integer","title":"Age","description":"Age as given."},"weight_kg":{"type":"number","title":"Weight Kg","description":"Weight as given."},"height_cm":{"type":"number","title":"Height Cm","description":"Height as given."},"activity_level":{"type":"string","title":"Activity Level","description":"Activity level used."},"activity_multiplier":{"type":"number","title":"Activity Multiplier","description":"The multiplier applied to BMR."},"activity_description":{"type":"string","title":"Activity Description","description":"What that level means in practice."},"bmr":{"type":"number","title":"Bmr","description":"The basal metabolic rate the answer used."},"bmr_formula_used":{"type":"string","title":"Bmr Formula Used","description":"Which formula, and why that one."},"bmr_mifflin_st_jeor":{"type":"number","title":"Bmr Mifflin St Jeor","description":"Mifflin-St Jeor (1990)."},"bmr_harris_benedict":{"type":"number","title":"Bmr Harris Benedict","description":"Revised Harris-Benedict (1984). Tends to read high."},"bmr_katch_mcardle":{"type":"number","title":"Bmr Katch Mcardle","description":"Katch-McArdle, or zero when body fat was not given."},"formula_spread_kcal":{"type":"number","title":"Formula Spread Kcal","description":"The gap between the highest and lowest formula. Often larger than the deficit someone is trying to run, which is why the formula used is named rather than averaged."},"tdee":{"type":"number","title":"Tdee","description":"Total daily energy expenditure, the maintenance figure."},"goal":{"type":"string","title":"Goal","description":"Goal as given."},"daily_calorie_target":{"type":"number","title":"Daily Calorie Target","description":"TDEE plus the goal offset."},"daily_offset":{"type":"number","title":"Daily Offset","description":"The offset applied: -500, 0 or +300."},"projected_weekly_change_kg":{"type":"number","title":"Projected Weekly Change Kg","description":"At 7,700 kcal per kilogram of body fat."},"protein_g":{"type":"number","title":"Protein G","description":"Daily protein target in grams."},"fat_g":{"type":"number","title":"Fat G","description":"Daily fat target in grams."},"carbs_g":{"type":"number","title":"Carbs G","description":"Daily carbohydrate target in grams."},"protein_kcal":{"type":"number","title":"Protein Kcal","description":"Calories from protein."},"fat_kcal":{"type":"number","title":"Fat Kcal","description":"Calories from fat."},"carbs_kcal":{"type":"number","title":"Carbs Kcal","description":"Calories from carbohydrate."},"minimum_fat_applied":{"type":"boolean","title":"Minimum Fat Applied","description":"True when fat was raised to the 0.8 g per kg floor."},"weeks_to_target":{"type":"number","title":"Weeks To Target","description":"Weeks to the target weight at this offset, or 0 if not applicable."},"caveats":{"items":{"type":"string"},"type":"array","title":"Caveats","description":"What these numbers are and are not. Worth passing on."}},"type":"object","required":["sex","age","weight_kg","height_cm","activity_level","activity_multiplier","activity_description","bmr","bmr_formula_used","bmr_mifflin_st_jeor","bmr_harris_benedict","bmr_katch_mcardle","formula_spread_kcal","tdee","goal","daily_calorie_target","daily_offset","projected_weekly_change_kg","protein_g","fat_g","carbs_g","protein_kcal","fat_kcal","carbs_kcal","minimum_fat_applied","weeks_to_target","caveats"],"title":"EnergyExpenditureResult"},"FbtRequest":{"properties":{"benefit_type":{"type":"string","enum":["vehicle","loan","other"],"title":"Benefit Type","description":"Which benefit. A vehicle is valued from the car, a loan from the gap between the prescribed rate and the rate charged, and 'other' takes a taxable value you supply.","default":"vehicle"},"rate_method":{"type":"string","enum":["single","alternate"],"title":"Rate Method","description":"63.93% single rate, or the 49.25% alternate rate. The alternate rate is available in quarters one to three only and forces a quarter four wash-up, so it is not simply cheaper.","default":"single"},"vehicle_value":{"type":"number","minimum":0.0,"title":"Vehicle Value","description":"Vehicle only. GST-inclusive cost price, or tax book value.","default":0.0},"value_method":{"type":"string","enum":["cost_price","tax_book_value"],"title":"Value Method","description":"Vehicle only. Cost price is 5% a quarter of what the employer paid and never falls. Tax book value is 9% a quarter of the written-down value, with a floor of $8,333.","default":"cost_price"},"days_available":{"type":"number","minimum":0.0,"title":"Days Available","description":"Vehicle only. Days the vehicle was available for private use. The divisor is always 90 under s RD 29(5)(a), never the actual length of the quarter. Values above 90 are capped.","default":90.0},"employee_contribution":{"type":"number","minimum":0.0,"title":"Employee Contribution","description":"Vehicle only. What the employee paid towards the benefit this quarter.","default":0.0},"loan_balance":{"type":"number","minimum":0.0,"title":"Loan Balance","description":"Loan only. Average balance for the quarter.","default":0.0},"prescribed_rate_pct":{"type":"number","minimum":0.0,"title":"Prescribed Rate Pct","description":"Loan only. IRD prescribed rate as a PERCENTAGE. Use the rate for the quarter being filed, not the current one.","default":0.0},"actual_rate_pct":{"type":"number","minimum":0.0,"title":"Actual Rate Pct","description":"Loan only. Rate actually charged, as a percentage.","default":0.0},"other_quarterly_value":{"type":"number","minimum":0.0,"title":"Other Quarterly Value","description":"Other benefits only. Quarterly taxable value.","default":0.0}},"type":"object","title":"FbtRequest","example":{"actual_rate_pct":0,"benefit_type":"vehicle","days_available":90,"employee_contribution":0,"loan_balance":0,"other_quarterly_value":0,"prescribed_rate_pct":0,"rate_method":"single","value_method":"cost_price","vehicle_value":45000}},"FbtResponse":{"properties":{"result":{"$ref":"#/components/schemas/FbtResult","description":"Quarterly taxable value and the FBT on it."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"FbtResponse","example":{"disclaimer":"Indicative FBT for one benefit for one employee, on current IRD rates. It does not pool or attribute benefits, and does not run the quarter four wash-up. Confirm your liability with a tax adviser before filing.","result":{"annual_fbt":5753.7,"benefit_type":"vehicle","excludes":["Pooling and attribution across multiple employees","The quarter four wash-up, in any of its three forms","Separate treatment of major shareholder-employees","GST on the fringe benefit, which is a separate adjustment"],"fbt_rate_pct":63.93,"notes":["Cost price is the GST-inclusive price the employer paid, and it does not fall as the vehicle ages.","The single rate applies to every employee regardless of income and needs no wash-up, which is why most small employers use it.","annual_fbt assumes the benefit is unchanged for four quarters. A vehicle bought or sold mid-year, or a loan being repaid, will not be."],"quarter_four_washup_required":false,"quarterly_fbt":1438.43,"quarterly_taxable_value":2250.0,"rate_method":"single","working":"$45,000 x 5% x (90/90 days) = $2,250.00 quarterly taxable value."}}},"FbtResult":{"properties":{"benefit_type":{"type":"string","title":"Benefit Type","description":"Benefit valued."},"rate_method":{"type":"string","title":"Rate Method","description":"Rate method used."},"fbt_rate_pct":{"type":"number","title":"Fbt Rate Pct","description":"The rate applied, as a percentage."},"quarterly_taxable_value":{"type":"number","title":"Quarterly Taxable Value","description":"Taxable value of the benefit for the quarter, after any contribution."},"quarterly_fbt":{"type":"number","title":"Quarterly Fbt","description":"FBT payable for the quarter."},"annual_fbt":{"type":"number","title":"Annual Fbt","description":"The quarter times four. Only the real annual liability if the benefit is unchanged all year."},"quarter_four_washup_required":{"type":"boolean","title":"Quarter Four Washup Required","description":"True whenever the alternate rate is used. The wash-up can claw back the saving, so never quote the alternate rate as cheaper without saying this."},"working":{"type":"string","title":"Working","description":"The arithmetic, in one line, for showing your work."},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"What applied, and what to watch for."},"excludes":{"items":{"type":"string"},"type":"array","title":"Excludes","description":"What this deliberately does not do."}},"type":"object","required":["benefit_type","rate_method","fbt_rate_pct","quarterly_taxable_value","quarterly_fbt","annual_fbt","quarter_four_washup_required","working","notes","excludes"],"title":"FbtResult"},"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 entirely: under twelve months the payout is 8% of gross earnings, not a leave balance.","default":"over12"},"leave_balance_days":{"type":"number","minimum":0.0,"title":"Leave Balance Days","description":"Unused annual leave in DAYS. Used when service is over12.","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.","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}},"type":"object","title":"FinalPayRequest","example":{"annual_salary":78000,"average_weekly_earnings":0.0,"gross_earnings_total":0.0,"hourly_rate":0.0,"hours_per_week":40,"leave_balance_days":12,"notice_weeks":4,"redundancy":0.0,"service":"over12"}},"FinalPayResponse":{"properties":{"result":{"$ref":"#/components/schemas/FinalPayResult","description":"Final pay components, gross."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"FinalPayResponse","example":{"disclaimer":"Gross estimate under the Holidays Act 2003. Excludes ordinary wages for days actually worked, which are paid on top, and excludes PAYE. Leave is paid at the greater of ordinary weekly pay and average weekly earnings; ordinary weekly pay is used unless you supply the average. Not legal or employment advice.","result":{"annual_gross":78000.0,"excludes":["ordinary wages for days actually worked in the final pay period, which are paid at the usual rate on top of this","PAYE and other deductions: every figure here is gross","any alternative (worked public) holidays owed"],"leave_basis":"ordinary weekly pay","leave_payout":3600.0,"leave_working":"Unused leave: 12 days x daily rate of $300.00 (based on ordinary weekly pay / 5) = $3,600.00.","notice_pay":6000.0,"notice_weeks":4.0,"redundancy":0.0,"service":"over12","tax_year":"2026/27","total_final_pay":9600.0,"weekly_gross":1500.0}}},"FinalPayResult":{"properties":{"weekly_gross":{"type":"number","title":"Weekly Gross","description":"Ordinary weekly pay."},"annual_gross":{"type":"number","title":"Annual Gross","description":"Annualised pay."},"service":{"type":"string","title":"Service","description":"Which branch was used, over12 or under12."},"leave_payout":{"type":"number","title":"Leave Payout","description":"Annual leave paid out, gross."},"leave_basis":{"type":"string","title":"Leave Basis","description":"What the leave payout was calculated on."},"leave_working":{"type":"string","title":"Leave Working","description":"The leave calculation written out."},"notice_weeks":{"type":"number","title":"Notice Weeks","description":"Weeks of notice paid."},"notice_pay":{"type":"number","title":"Notice Pay","description":"Notice pay, gross."},"redundancy":{"type":"number","title":"Redundancy","description":"Redundancy compensation as given."},"total_final_pay":{"type":"number","title":"Total Final Pay","description":"Sum of the three, gross."},"excludes":{"items":{"type":"string"},"type":"array","title":"Excludes","description":"What this total does NOT include. Ordinary wages for days worked are the big one: they are paid on top."},"tax_year":{"type":"string","title":"Tax Year","description":"Tax year the figures relate to."}},"type":"object","required":["weekly_gross","annual_gross","service","leave_payout","leave_basis","leave_working","notice_weeks","notice_pay","redundancy","total_final_pay","excludes","tax_year"],"title":"FinalPayResult"},"FindCalculatorHit":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Page title."},"url":{"type":"string","title":"Url","description":"Full URL on calculate.co.nz."},"type":{"type":"string","title":"Type","description":"One of calculator, tool, guide or dataset."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Section of the site the page sits in."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"One line on what the page does."},"score":{"type":"number","title":"Score","description":"Relevance, higher is better. Comparable within one response only, not across different queries."}},"type":"object","required":["url","type","score"],"title":"FindCalculatorHit"},"FindCalculatorRequest":{"properties":{"query":{"type":"string","maxLength":200,"minLength":1,"title":"Query","description":"What to work out, in plain language."},"limit":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Limit","description":"Number of results, 1 to 20.","default":5},"types":{"anyOf":[{"items":{"type":"string","enum":["calculator","tool","guide","dataset"]},"type":"array"},{"type":"null"}],"title":"Types","description":"Restrict to these page types. Omit for all types."}},"type":"object","required":["query"],"title":"FindCalculatorRequest","example":{"limit":5,"query":"how much tax do I pay on my salary"}},"FindCalculatorResponse":{"properties":{"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"The query as searched."},"count":{"type":"integer","title":"Count","description":"Number of results returned, at most `limit`.","default":0},"results":{"items":{"$ref":"#/components/schemas/FindCalculatorHit"},"type":"array","title":"Results","description":"Matches, best first.","default":[]},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Where the page index was loaded from."},"index_pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Index Pages","description":"Pages in the index at the time of the search."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Set only when the index could not be loaded. Results will be empty."}},"type":"object","title":"FindCalculatorResponse"},"FuelCostRequest":{"properties":{"distance_km":{"type":"number","minimum":0.0,"title":"Distance Km","description":"Trip distance in kilometres."},"consumption_l_per_100km":{"type":"number","exclusiveMinimum":0.0,"title":"Consumption L Per 100Km","description":"Vehicle consumption in litres per 100 km, the New Zealand convention, so a LOWER number is a more efficient vehicle. This is not miles per gallon and not kilometres per litre."},"price_per_litre":{"type":"number","minimum":0.0,"title":"Price Per Litre","description":"Pump price in NZD per litre."},"weekly_km":{"type":"number","minimum":0.0,"title":"Weekly Km","description":"Kilometres driven in a typical week, used for the running costs. Leave at zero for a one-off trip: the weekly, monthly and annual figures then come back as zero rather than as an error.","default":0}},"type":"object","required":["distance_km","consumption_l_per_100km","price_per_litre"],"title":"FuelCostRequest","example":{"consumption_l_per_100km":7.8,"distance_km":642,"price_per_litre":2.79,"weekly_km":250}},"FuelCostResponse":{"properties":{"result":{"$ref":"#/components/schemas/FuelCostResult","description":"Trip cost and ongoing running costs."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"FuelCostResponse","example":{"disclaimer":"Estimate only. Real consumption varies with driving style, load, terrain, traffic and tyre pressure, and pump prices move daily. Fuel only: this is not the full cost of running a vehicle.","result":{"annual_cost":2829.0,"annual_km":13000.0,"consumption_l_per_100km":7.8,"cost_per_100km":21.76,"cost_per_km":0.22,"distance_km":642.0,"litres_used":50.1,"monthly_cost":235.76,"price_per_litre":2.79,"trip_cost":139.71,"weekly_cost":54.41,"weekly_km":250.0}}},"FuelCostResult":{"properties":{"distance_km":{"type":"number","title":"Distance Km","description":"Trip distance you sent, in kilometres."},"consumption_l_per_100km":{"type":"number","title":"Consumption L Per 100Km","description":"Consumption you sent, L/100km."},"price_per_litre":{"type":"number","title":"Price Per Litre","description":"Pump price you sent, NZD per litre."},"weekly_km":{"type":"number","title":"Weekly Km","description":"Weekly distance you sent, in kilometres."},"litres_used":{"type":"number","title":"Litres Used","description":"Fuel the trip consumes, in litres."},"trip_cost":{"type":"number","title":"Trip Cost","description":"What the trip costs in fuel, in NZD."},"cost_per_km":{"type":"number","title":"Cost Per Km","description":"Fuel cost of one kilometre. Zero when distance_km is zero, rather than an error, matching the website."},"cost_per_100km":{"type":"number","title":"Cost Per 100Km","description":"Fuel cost of 100 km, which is consumption times price and does not depend on the trip distance. Useful for comparing vehicles."},"weekly_cost":{"type":"number","title":"Weekly Cost","description":"Fuel cost of a typical week, from weekly_km."},"monthly_cost":{"type":"number","title":"Monthly Cost","description":"A twelfth of the annual cost, NOT the weekly cost times 4.33 and not a calendar month. Matches the website."},"annual_cost":{"type":"number","title":"Annual Cost","description":"Weekly cost over 52 weeks, in NZD."},"annual_km":{"type":"number","title":"Annual Km","description":"Weekly distance over 52 weeks, in kilometres."}},"type":"object","required":["distance_km","consumption_l_per_100km","price_per_litre","weekly_km","litres_used","trip_cost","cost_per_km","cost_per_100km","weekly_cost","monthly_cost","annual_cost","annual_km"],"title":"FuelCostResult"},"GPACourseInput":{"properties":{"grade":{"type":"string","title":"Grade","description":"Grade for the paper. A+ through C- carry points; D+ and below are zero."},"credits":{"type":"number","minimum":0.0,"title":"Credits","description":"Credit value of the paper, commonly 15 in NZ."}},"type":"object","required":["grade","credits"],"title":"GPACourseInput"},"GPACourseResult":{"properties":{"grade":{"type":"string","title":"Grade","description":"Grade as matched, upper-cased."},"credits":{"type":"number","title":"Credits","description":"Credits for the paper."},"grade_points":{"type":"number","title":"Grade Points","description":"Points that grade is worth on the scale."},"weighted_points":{"type":"number","title":"Weighted Points","description":"Points times credits, this paper's contribution."}},"type":"object","required":["grade","credits","grade_points","weighted_points"],"title":"GPACourseResult"},"GPARequest":{"properties":{"courses":{"items":{"$ref":"#/components/schemas/GPACourseInput"},"type":"array","minItems":1,"title":"Courses","description":"One entry per paper. Papers with zero credits are ignored."},"scale":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Scale","description":"Override the points for particular grades if your institution differs. Anything not named keeps its New Zealand value."}},"type":"object","required":["courses"],"title":"GPARequest","example":{"courses":[{"credits":15,"grade":"A"},{"credits":15,"grade":"B+"},{"credits":15,"grade":"A-"},{"credits":15,"grade":"B"}]}},"GPAResponse":{"properties":{"result":{"$ref":"#/components/schemas/GPAResult","description":"The GPA and how it was arrived at."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"GPAResponse","example":{"disclaimer":"Indicative only. New Zealand universities differ in how they weight papers, treat failed and repeated papers, and calculate an award GPA. The record your institution holds is the one that counts.","result":{"courses":[{"credits":15.0,"grade":"A","grade_points":8.0,"weighted_points":120.0},{"credits":15.0,"grade":"B+","grade_points":6.0,"weighted_points":90.0},{"credits":15.0,"grade":"A-","grade_points":7.0,"weighted_points":105.0},{"credits":15.0,"grade":"B","grade_points":5.0,"weighted_points":75.0}],"courses_counted":4,"gpa":6.5,"scale":"New Zealand 9-point","total_credits":60.0,"total_weighted_points":390.0}}},"GPAResult":{"properties":{"gpa":{"type":"number","title":"Gpa","description":"Credit-weighted grade point average on the NEW ZEALAND NINE POINT scale, where A+ is 9. This is not a 4.0 GPA: 7.0 here is a strong result, and the two scales do not convert by simple scaling."},"total_credits":{"type":"number","title":"Total Credits","description":"Credits counted, including failed papers."},"total_weighted_points":{"type":"number","title":"Total Weighted Points","description":"Sum of points times credits."},"courses_counted":{"type":"integer","title":"Courses Counted","description":"Papers with credits above zero."},"courses":{"items":{"$ref":"#/components/schemas/GPACourseResult"},"type":"array","title":"Courses","description":"Each paper's contribution, so the total can be checked."},"scale":{"type":"string","title":"Scale","description":"Which scale was applied."}},"type":"object","required":["gpa","total_credits","total_weighted_points","courses_counted","courses","scale"],"title":"GPAResult"},"GSTRequest":{"properties":{"amount":{"type":"number","minimum":0.0,"title":"Amount","description":"Dollar amount in NZD"},"mode":{"type":"string","enum":["add","remove"],"title":"Mode","description":"'add' treats amount as GST-exclusive; 'remove' as GST-inclusive.","default":"add"},"gst_rate":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Gst Rate","description":"GST rate as a decimal. NZ standard 0.15 (15%).","default":0.15}},"type":"object","required":["amount"],"title":"GSTRequest","example":{"amount":100.0,"gst_rate":0.15,"mode":"add"}},"GSTResponse":{"properties":{"result":{"$ref":"#/components/schemas/GSTResult","description":"The amount split three ways."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"GSTResponse","example":{"disclaimer":"Calculation based on standard NZ GST rate. Not tax advice.","result":{"amount_excl_gst":100.0,"amount_incl_gst":115.0,"gst_content":15.0,"gst_rate":0.15,"input_amount":100.0,"mode":"add"}}},"GSTResult":{"properties":{"input_amount":{"type":"number","title":"Input Amount","description":"The amount you sent, unchanged."},"gst_rate":{"type":"number","title":"Gst Rate","description":"Rate applied, as a decimal."},"mode":{"type":"string","title":"Mode","description":"Whether GST was added or removed."},"amount_excl_gst":{"type":"number","title":"Amount Excl Gst","description":"Amount before GST."},"gst_content":{"type":"number","title":"Gst Content","description":"The GST portion itself."},"amount_incl_gst":{"type":"number","title":"Amount Incl Gst","description":"Amount including GST."}},"type":"object","required":["input_amount","gst_rate","mode","amount_excl_gst","gst_content","amount_incl_gst"],"title":"GSTResult"},"GroceryBudgetRequest":{"properties":{"members":{"items":{"type":"string","enum":["child_5_10","teen_11_17","adult_male","adult_female","elderly_65"]},"type":"array","maxItems":12,"minItems":1,"title":"Members","description":"One entry per person in the household. A teenager is not a child-sized cost."},"spend_level":{"type":"string","enum":["basic","moderate","liberal"],"title":"Spend Level","description":"How the household shops.","default":"moderate"},"diet":{"type":"string","enum":["standard","vegetarian","vegan","gluten_free","organic","halal"],"title":"Diet","description":"Diet, applied as a multiplier to the food cost.","default":"standard"},"region":{"type":"string","enum":["nz_average","auckland","wellington","christchurch","hamilton","tauranga","dunedin","provincial","rural_remote"],"title":"Region","description":"Where they shop.","default":"nz_average"},"include_non_food":{"type":"boolean","title":"Include Non Food","description":"Include $25 a week for cleaning products and toiletries. Most people counting a supermarket bill are including these.","default":true}},"type":"object","required":["members"],"title":"GroceryBudgetRequest","example":{"diet":"standard","include_non_food":true,"members":["adult_male","adult_female","teen_11_17","child_5_10"],"region":"nz_average","spend_level":"moderate"}},"GroceryBudgetResponse":{"properties":{"result":{"$ref":"#/components/schemas/GroceryBudgetResult","description":"A grocery budget for the household."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"GroceryBudgetResponse","example":{"disclaimer":"Indicative planning figures for a New Zealand household, not measured survey data and not a benchmark. Use them to start a budget.","result":{"annual_by_level":{"basic":12740.0,"liberal":22100.0,"moderate":16900.0},"annual_gap_basic_to_liberal":9360.0,"annual_total":16900.0,"base_weekly_food":300.0,"diet":"standard","diet_multiplier":1.0,"excludes":["Alcohol, tobacco and takeaways","Pet food","Any particular supermarket's prices, or current promotions","Food price inflation since the figures were set"],"household_size":4,"include_non_food":true,"members":["adult_male","adult_female","teen_11_17","child_5_10"],"monthly_total":1407.25,"non_food_weekly":25.0,"notes":["The per-person costs are indicative planning figures used by the website calculator, not a measured survey result. Treat them as a starting point for a budget, not a benchmark.","Every spend level is returned. The gap between basic and liberal for the same household, $9,360 a year here, is more useful than any single figure."],"per_person_weekly":81.25,"region":"nz_average","region_multiplier":1.0,"spend_level":"moderate","weekly_by_level":{"basic":245.0,"liberal":425.0,"moderate":325.0},"weekly_total":325.0}}},"GroceryBudgetResult":{"properties":{"members":{"items":{"type":"string"},"type":"array","title":"Members","description":"Household as given."},"household_size":{"type":"integer","title":"Household Size","description":"Number of people."},"spend_level":{"type":"string","title":"Spend Level","description":"Spend level used."},"diet":{"type":"string","title":"Diet","description":"Diet used."},"diet_multiplier":{"type":"number","title":"Diet Multiplier","description":"Multiplier applied for the diet."},"region":{"type":"string","title":"Region","description":"Region used."},"region_multiplier":{"type":"number","title":"Region Multiplier","description":"Multiplier applied for the region."},"include_non_food":{"type":"boolean","title":"Include Non Food","description":"Whether non-food is included."},"non_food_weekly":{"type":"number","title":"Non Food Weekly","description":"Weekly non-food allowance applied."},"base_weekly_food":{"type":"number","title":"Base Weekly Food","description":"Food cost before diet and region adjustment."},"weekly_total":{"type":"number","title":"Weekly Total","description":"Weekly budget after all adjustments."},"monthly_total":{"type":"number","title":"Monthly Total","description":"Weekly times 4.33."},"annual_total":{"type":"number","title":"Annual Total","description":"Weekly times 52."},"weekly_by_level":{"additionalProperties":{"type":"number"},"type":"object","title":"Weekly By Level","description":"All three spend levels weekly, for the same household."},"annual_by_level":{"additionalProperties":{"type":"number"},"type":"object","title":"Annual By Level","description":"All three spend levels annually."},"annual_gap_basic_to_liberal":{"type":"number","title":"Annual Gap Basic To Liberal","description":"What the household's shopping habits are worth over a year. Usually the most useful number here."},"per_person_weekly":{"type":"number","title":"Per Person Weekly","description":"Weekly total divided by household size."},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"What applied, and what these figures are."},"excludes":{"items":{"type":"string"},"type":"array","title":"Excludes","description":"What is not in the budget."}},"type":"object","required":["members","household_size","spend_level","diet","diet_multiplier","region","region_multiplier","include_non_food","non_food_weekly","base_weekly_food","weekly_total","monthly_total","annual_total","weekly_by_level","annual_by_level","annual_gap_basic_to_liberal","per_person_weekly","notes","excludes"],"title":"GroceryBudgetResult"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HourlyToSalaryRequest":{"properties":{"hourly_rate":{"type":"number","minimum":0.0,"title":"Hourly Rate","description":"Gross pay per hour in NZD."},"hours_per_week":{"type":"number","exclusiveMinimum":0.0,"title":"Hours Per Week","description":"Ordinary hours a week. 40 is full time.","default":40},"weeks_per_year":{"type":"number","maximum":53.0,"exclusiveMinimum":0.0,"title":"Weeks Per Year","description":"Weeks actually paid. Fewer for seasonal, academic or fixed-term work.","default":52},"kiwisaver_rate":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Kiwisaver Rate","description":"Employee contribution as a DECIMAL: 0.03 for 3%, not 3.","default":0},"has_student_loan":{"type":"boolean","title":"Has Student Loan","description":"Whether repayments are deducted.","default":false}},"type":"object","required":["hourly_rate"],"title":"HourlyToSalaryRequest","example":{"has_student_loan":false,"hourly_rate":32.5,"hours_per_week":40,"kiwisaver_rate":0.03,"weeks_per_year":52}},"HourlyToSalaryResponse":{"properties":{"result":{"$ref":"#/components/schemas/HourlyToSalaryResult","description":"Gross, deductions and take-home."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"HourlyToSalaryResponse","example":{"disclaimer":"Estimate only based on standard PAYE rules for salary and wages. Does not account for secondary income, ESCT differences or non-resident status. Not financial or tax advice.","result":{"acc_levy":1183.0,"effective_hourly_after_tax":25.1,"gross_annual":67600.0,"gross_fortnightly":2600.0,"gross_monthly":5633.33,"gross_weekly":1300.0,"hourly_rate":32.5,"hours_per_week":40.0,"kiwisaver":2028.0,"net_annual":52200.5,"net_weekly":1003.86,"paye":12188.5,"student_loan":0.0,"total_deductions":15399.5,"weeks_per_year":52.0}}},"HourlyToSalaryResult":{"properties":{"hourly_rate":{"type":"number","title":"Hourly Rate","description":"Rate you sent."},"hours_per_week":{"type":"number","title":"Hours Per Week","description":"Hours a week you sent."},"weeks_per_year":{"type":"number","title":"Weeks Per Year","description":"Weeks a year you sent."},"gross_weekly":{"type":"number","title":"Gross Weekly","description":"Gross pay for one week."},"gross_fortnightly":{"type":"number","title":"Gross Fortnightly","description":"Two weeks of gross pay."},"gross_monthly":{"type":"number","title":"Gross Monthly","description":"A twelfth of the annual gross."},"gross_annual":{"type":"number","title":"Gross Annual","description":"Weekly gross times weeks worked."},"paye":{"type":"number","title":"Paye","description":"Income tax for the year, after any IETC."},"acc_levy":{"type":"number","title":"Acc Levy","description":"ACC earner levy, 1.75% up to the cap."},"kiwisaver":{"type":"number","title":"Kiwisaver","description":"Your KiwiSaver contribution."},"student_loan":{"type":"number","title":"Student Loan","description":"Repayments at 12% above the threshold."},"total_deductions":{"type":"number","title":"Total Deductions","description":"Everything taken off the gross."},"net_annual":{"type":"number","title":"Net Annual","description":"Take-home pay for the year."},"net_weekly":{"type":"number","title":"Net Weekly","description":"Net annual divided by 52, ALWAYS 52 even for a shorter working year, so it is what lands each week across the whole year."},"effective_hourly_after_tax":{"type":"number","title":"Effective Hourly After Tax","description":"Net pay divided by hours ACTUALLY worked, so this uses weeks_per_year rather than 52. What an hour was really worth, and the figure to compare a wage job against a salaried one."}},"type":"object","required":["hourly_rate","hours_per_week","weeks_per_year","gross_weekly","gross_fortnightly","gross_monthly","gross_annual","paye","acc_levy","kiwisaver","student_loan","total_deductions","net_annual","net_weekly","effective_hourly_after_tax"],"title":"HourlyToSalaryResult"},"KiwiSaverRequest":{"properties":{"current_balance":{"type":"number","minimum":0.0,"title":"Current Balance","description":"Starting balance in NZD"},"current_age":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Current Age","description":"Age now, in whole years."},"retirement_age":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Retirement Age","description":"Age the projection runs to. 65 is when NZ Super starts.","default":65},"annual_income":{"type":"number","minimum":0.0,"title":"Annual Income","description":"Gross annual salary in NZD, before tax.","default":100000},"income_growth_pct":{"type":"number","maximum":50.0,"minimum":0.0,"title":"Income Growth Pct","description":"Assumed pay rise each year, as a percentage.","default":1.0},"employee_rate_pct":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Employee Rate Pct","description":"Your contribution rate. NZ options are 3, 3.5, 4, 6, 8 or 10.","default":3.5},"employer_rate_pct":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Employer Rate Pct","description":"Employer contribution rate. The compulsory minimum is 3.5% from 1 April 2026.","default":3.5},"voluntary_amount":{"type":"number","minimum":0.0,"title":"Voluntary Amount","description":"Extra contribution on top of salary deductions, in NZD.","default":0},"voluntary_frequency":{"type":"string","enum":["week","fortnight","month","year"],"title":"Voluntary Frequency","description":"How often the voluntary amount is paid.","default":"month"},"fund_type":{"type":"string","enum":["Cash","Conservative","Balanced","Growth","Custom"],"title":"Fund Type","description":"Fund risk profile, which sets the assumed return unless Custom.","default":"Conservative"},"custom_return_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Custom Return Pct","description":"Annual return to assume. Required if fund_type is 'Custom'."},"pir_rate_pct":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Pir Rate Pct","description":"Prescribed Investor Rate as a percentage: 10.5, 17.5 or 28.","default":28.0},"annual_fee_pct":{"type":"number","maximum":10.0,"minimum":0.0,"title":"Annual Fee Pct","description":"Total annual fund fee, as a percentage of balance.","default":0.4},"inflation_pct":{"type":"number","maximum":50.0,"minimum":0.0,"title":"Inflation Pct","description":"Assumed inflation, used only for the today's-dollars figure.","default":3.0},"switch_fund_at_age":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Switch Fund At Age","description":"Age to switch funds, for a de-risking plan. Omit for no switch."},"switch_to_fund":{"anyOf":[{"type":"string","enum":["Cash","Conservative","Balanced","Growth","Custom"]},{"type":"null"}],"title":"Switch To Fund","description":"Fund to switch into at switch_fund_at_age."},"switch_custom_return_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Switch Custom Return Pct","description":"Return after switching. Required if switch_to_fund is 'Custom'."}},"type":"object","required":["current_balance","current_age"],"title":"KiwiSaverRequest","example":{"annual_income":90000,"current_age":35,"current_balance":25000,"retirement_age":65}},"KiwiSaverResponse":{"properties":{"result":{"$ref":"#/components/schemas/KiwiSaverResult","description":"Projected balance and its components."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this projection."}},"type":"object","required":["result","disclaimer"],"title":"KiwiSaverResponse","example":{"disclaimer":"Projection only. Actual outcomes depend on market returns, fee changes, rule changes, and contribution history. Investment returns are assumed constant; real-world returns vary. Not financial advice.","result":{"final_annual_income":121306.38,"final_balance":279905.19,"final_balance_real_todays_dollars":115317.23,"inputs":{"annual_fee_pct":0.4,"annual_income":90000.0,"current_age":35,"current_balance":25000.0,"employee_rate_pct":3.5,"employer_rate_pct":3.5,"fund_type":"Conservative","income_growth_pct":1.0,"inflation_pct":3.0,"pir_rate_pct":28.0,"retirement_age":65,"voluntary_amount":0.0,"voluntary_frequency":"month"},"months_projected":360,"total_employee_contributions":109572.48,"total_employer_contributions_net":78891.96,"total_fees_paid":16622.3,"total_government_contributions":7821.6,"total_investment_gains_net":75241.42,"total_voluntary_contributions":0.0,"years_to_retirement":30}}},"KiwiSaverResult":{"properties":{"final_balance":{"type":"number","title":"Final Balance","description":"Projected balance at retirement age, in future dollars."},"final_balance_real_todays_dollars":{"type":"number","title":"Final Balance Real Todays Dollars","description":"The same balance deflated by inflation_pct. This is the figure to compare against what things cost today."},"total_employee_contributions":{"type":"number","title":"Total Employee Contributions","description":"Everything you contribute from salary."},"total_employer_contributions_net":{"type":"number","title":"Total Employer Contributions Net","description":"Employer contributions after ESCT is deducted."},"total_voluntary_contributions":{"type":"number","title":"Total Voluntary Contributions","description":"Everything contributed on top of salary."},"total_government_contributions":{"type":"number","title":"Total Government Contributions","description":"Total government contribution over the projection."},"total_investment_gains_net":{"type":"number","title":"Total Investment Gains Net","description":"Investment returns after tax at your PIR."},"total_fees_paid":{"type":"number","title":"Total Fees Paid","description":"Total fund fees over the projection."},"years_to_retirement":{"type":"number","title":"Years To Retirement","description":"Years from current_age to retirement_age."},"months_projected":{"type":"integer","title":"Months Projected","description":"Number of monthly steps the projection ran."},"final_annual_income":{"type":"number","title":"Final Annual Income","description":"Salary in the final year, after income_growth_pct compounding."},"inputs":{"additionalProperties":true,"type":"object","title":"Inputs","description":"The inputs used, echoed back with defaults filled in."}},"type":"object","required":["final_balance","final_balance_real_todays_dollars","total_employee_contributions","total_employer_contributions_net","total_voluntary_contributions","total_government_contributions","total_investment_gains_net","total_fees_paid","years_to_retirement","months_projected","final_annual_income","inputs"],"title":"KiwiSaverResult"},"LumpSumTaxRequest":{"properties":{"lump_sum":{"type":"number","minimum":0.0,"title":"Lump Sum","description":"The gross lump sum in NZD."},"annual_salary":{"type":"number","minimum":0.0,"title":"Annual Salary","description":"Annual salary, used as the annualised income. This selects the rate, so the answer depends on it."},"payment_type":{"type":"string","title":"Payment Type","description":"redundancy, retirement, bonus, commission, holiday_pay, exit_inducement or back_pay. Redundancy and retirement carry no ACC levy and take no KiwiSaver, which changes the answer.","default":"redundancy"},"kiwisaver_rate":{"type":"number","exclusiveMaximum":1.0,"minimum":0.0,"title":"Kiwisaver Rate","description":"Employee contribution as a DECIMAL. Forced to zero for redundancy and retirement, because no KiwiSaver comes out of those.","default":0.0},"has_student_loan":{"type":"boolean","title":"Has Student Loan","description":"Whether 12% is deducted from the lump sum.","default":false}},"type":"object","required":["lump_sum","annual_salary"],"title":"LumpSumTaxRequest","example":{"annual_salary":75000,"has_student_loan":false,"kiwisaver_rate":0.0,"lump_sum":15000,"payment_type":"redundancy"}},"LumpSumTaxResponse":{"properties":{"result":{"$ref":"#/components/schemas/LumpSumTaxResult","description":"Rate applied and what is left."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"LumpSumTaxResponse","example":{"disclaimer":"Estimate only, using IRD lump sum PAYE rates as at 1 April 2026 with the annual salary taken as the annualised income. Your employer grosses up recent pay instead, which can select a higher row. Not tax advice.","result":{"annual_salary":75000.0,"annualised_income":75000.0,"bracket":"$78,101 to $156,641","effective_rate_percent":33.0,"excludes_acc_levy":true,"kiwisaver":0.0,"lump_sum":15000.0,"net_received":10050.0,"paye":4950.0,"paye_rate_percent":33.0,"payment_type":"redundancy","student_loan":0.0,"tax_year":"2026/27","total_deductions":4950.0,"total_for_rate":90000.0,"why_that_rate":"A redundancy payment carries no ACC earner levy, so the excluding-ACC column applies whatever the income. Annualised income 75,000.00 plus the lump sum puts the total in $78,101 to $156,641."}}},"LumpSumTaxResult":{"properties":{"payment_type":{"type":"string","title":"Payment Type","description":"The payment type used."},"lump_sum":{"type":"number","title":"Lump Sum","description":"Gross lump sum."},"annual_salary":{"type":"number","title":"Annual Salary","description":"Salary as given."},"annualised_income":{"type":"number","title":"Annualised Income","description":"The annualised income the rate was selected on. IRD grosses up the last four weeks; this uses the salary, which is the same for steady pay. Shown so the substitution is visible."},"total_for_rate":{"type":"number","title":"Total For Rate","description":"Annualised income plus the lump sum."},"bracket":{"type":"string","title":"Bracket","description":"The band that total falls in."},"paye_rate_percent":{"type":"number","title":"Paye Rate Percent","description":"The single flat rate applied to the whole lump sum."},"excludes_acc_levy":{"type":"boolean","title":"Excludes Acc Levy","description":"True when the lower column applies: always for redundancy and retirement, and for anything once the total passes the ACC cap."},"why_that_rate":{"type":"string","title":"Why That Rate","description":"Why that row of the table was selected."},"paye":{"type":"number","title":"Paye","description":"PAYE deducted from the lump sum."},"kiwisaver":{"type":"number","title":"Kiwisaver","description":"KiwiSaver deducted. Always zero for redundancy."},"student_loan":{"type":"number","title":"Student Loan","description":"Student loan deducted, 12% of the whole lump sum."},"total_deductions":{"type":"number","title":"Total Deductions","description":"Everything taken off."},"net_received":{"type":"number","title":"Net Received","description":"What actually arrives."},"effective_rate_percent":{"type":"number","title":"Effective Rate Percent","description":"All deductions as a percentage of the lump sum."},"tax_year":{"type":"string","title":"Tax Year","description":"Tax year the rate table is for."}},"type":"object","required":["payment_type","lump_sum","annual_salary","annualised_income","total_for_rate","bracket","paye_rate_percent","excludes_acc_levy","why_that_rate","paye","kiwisaver","student_loan","total_deductions","net_received","effective_rate_percent","tax_year"],"title":"LumpSumTaxResult"},"MortgageRequest":{"properties":{"loan_amount":{"type":"number","exclusiveMinimum":0.0,"title":"Loan Amount","description":"Principal borrowed in NZD"},"annual_interest_rate_pct":{"type":"number","minimum":0.0,"title":"Annual Interest Rate Pct","description":"Annual nominal rate as a percentage, e.g. 6.5"},"term_years":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Term Years","description":"Loan term in years"}},"type":"object","required":["loan_amount","annual_interest_rate_pct","term_years"],"title":"MortgageRequest","example":{"annual_interest_rate_pct":5.99,"loan_amount":750000,"term_years":30}},"MortgageResponse":{"properties":{"result":{"$ref":"#/components/schemas/MortgageResult","description":"Repayments and lifetime totals."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"MortgageResponse","example":{"disclaimer":"Estimate only using a constant nominal rate compounded monthly. Actual repayments depend on your lender's terms, fees, and rate changes. Not financial advice.","result":{"annual_interest_rate_pct":5.99,"fortnightly_repayment":2066.15,"interest_share_pct":53.62,"loan_amount":750000.0,"monthly_repayment":4491.81,"principal_share_pct":46.38,"term_years":30,"total_interest_paid":867050.94,"total_principal_paid":750000.0,"total_repayments":1617050.94,"weekly_repayment":1033.07}}},"MortgageResult":{"properties":{"loan_amount":{"type":"number","title":"Loan Amount","description":"Principal you sent, in NZD."},"annual_interest_rate_pct":{"type":"number","title":"Annual Interest Rate Pct","description":"Rate you sent, as a percentage."},"term_years":{"type":"integer","title":"Term Years","description":"Term you sent, in years."},"monthly_repayment":{"type":"number","title":"Monthly Repayment","description":"Repayment per month, the basis of the calculation."},"fortnightly_repayment":{"type":"number","title":"Fortnightly Repayment","description":"Monthly repayment divided by 2.174, the average fortnights in a month, which is how calculate.co.nz presents it. This is the same annual amount paid more often, NOT an accelerated schedule, so it does not shorten the term or reduce the interest below."},"weekly_repayment":{"type":"number","title":"Weekly Repayment","description":"Monthly repayment divided by 4.348, the average weeks in a month. Same caveat as fortnightly: paying weekly at this figure does not pay the loan off faster."},"total_repayments":{"type":"number","title":"Total Repayments","description":"Everything paid over the full term, on the monthly schedule. The fortnightly and weekly figures are restatements of it, so they do not produce a different total."},"total_interest_paid":{"type":"number","title":"Total Interest Paid","description":"Interest portion of the total."},"total_principal_paid":{"type":"number","title":"Total Principal Paid","description":"Principal portion, equal to the loan amount."},"principal_share_pct":{"type":"number","title":"Principal Share Pct","description":"Principal as a percentage of total repayments."},"interest_share_pct":{"type":"number","title":"Interest Share Pct","description":"Interest as a percentage of total repayments."}},"type":"object","required":["loan_amount","annual_interest_rate_pct","term_years","monthly_repayment","fortnightly_repayment","weekly_repayment","total_repayments","total_interest_paid","total_principal_paid","principal_share_pct","interest_share_pct"],"title":"MortgageResult"},"NceaRankScoreRequest":{"properties":{"excellence_credits":{"type":"integer","minimum":0.0,"title":"Excellence Credits","description":"Level 3 or above credits achieved with Excellence.","default":0},"merit_credits":{"type":"integer","minimum":0.0,"title":"Merit Credits","description":"Level 3 or above credits achieved with Merit.","default":0},"achieved_credits":{"type":"integer","minimum":0.0,"title":"Achieved Credits","description":"Level 3 or above credits achieved.","default":0},"not_achieved_credits":{"type":"integer","minimum":0.0,"title":"Not Achieved Credits","description":"Credits attempted and not achieved. They do NOT affect the rank score and they do lower the indicative GPA.","default":0}},"type":"object","title":"NceaRankScoreRequest","example":{"achieved_credits":20,"excellence_credits":40,"merit_credits":40,"not_achieved_credits":0}},"NceaRankScoreResponse":{"properties":{"result":{"$ref":"#/components/schemas/NceaRankScoreResult","description":"Rank score and indicative GPA."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"NceaRankScoreResponse","example":{"disclaimer":"The rank score follows the NZQA University Entrance method: best 80 credits at Level 3 or above. The 4-point GPA is an unofficial conversion, since NZQA issues no GPA. Some programmes use their own selection measures, so confirm requirements with the university.","result":{"achieved_credits":20,"credits_counted":80,"credits_ignored":20,"excellence_credits":40,"excludes":["NZQA issues no GPA. The 4-point figure is the widely used Excellence 4, Merit 3, Achieved 2 weighting and is indicative only.","Credits below Level 3 do not count towards the University Entrance rank score and should not be entered here.","Some programmes use their own selection measures on top of the rank score, so confirm entry requirements with the university."],"gpa_is_unofficial":true,"indicative_gpa_4_point":3.2,"merit_credits":40,"next_step":"20 credit(s) fell outside the best 80 and count for nothing. Lifting an existing subject from Achieved to Merit or Excellence raises the score; collecting more Achieved credits does not.","not_achieved_credits":0,"rank_score":280,"rank_score_max":320,"rank_score_working":"40 excellence x 4 = 160, 40 merit x 3 = 120, total 280 out of 320","total_credits":100}}},"NceaRankScoreResult":{"properties":{"excellence_credits":{"type":"integer","title":"Excellence Credits","description":"Excellence credits as given."},"merit_credits":{"type":"integer","title":"Merit Credits","description":"Merit credits as given."},"achieved_credits":{"type":"integer","title":"Achieved Credits","description":"Achieved credits as given."},"not_achieved_credits":{"type":"integer","title":"Not Achieved Credits","description":"Not Achieved credits as given."},"total_credits":{"type":"integer","title":"Total Credits","description":"Everything entered, including Not Achieved."},"rank_score":{"type":"integer","title":"Rank Score","description":"The University Entrance rank score, out of 320. This is the number New Zealand universities use to select for limited-entry courses."},"rank_score_max":{"type":"integer","title":"Rank Score Max","description":"320, being 80 credits at 4 points."},"credits_counted":{"type":"integer","title":"Credits Counted","description":"How many of the best 80 were used."},"credits_ignored":{"type":"integer","title":"Credits Ignored","description":"Achieving credits that fell outside the best 80 and count for nothing. Usually a surprise, and the reason improving a grade beats collecting more credits."},"rank_score_working":{"type":"string","title":"Rank Score Working","description":"The rank score calculation written out."},"indicative_gpa_4_point":{"type":"number","title":"Indicative Gpa 4 Point","description":"An UNOFFICIAL 4-point GPA, credit-weighted at Excellence 4, Merit 3, Achieved 2. NZQA issues no GPA."},"gpa_is_unofficial":{"type":"boolean","title":"Gpa Is Unofficial","description":"Always true. NZQA does not issue a GPA."},"next_step":{"type":"string","title":"Next Step","description":"What would actually raise the rank score for this student."},"excludes":{"items":{"type":"string"},"type":"array","title":"Excludes","description":"What this does not cover."}},"type":"object","required":["excellence_credits","merit_credits","achieved_credits","not_achieved_credits","total_credits","rank_score","rank_score_max","credits_counted","credits_ignored","rank_score_working","indicative_gpa_4_point","gpa_is_unofficial","next_step","excludes"],"title":"NceaRankScoreResult"},"NetToGrossRequest":{"properties":{"target_net":{"type":"number","minimum":0.0,"title":"Target Net","description":"The take-home wanted, in the period given by `period`."},"period":{"type":"string","title":"Period","description":"annual, monthly, fortnightly or weekly. The target is read in this period and the gross is reported in it too.","default":"annual"},"kiwisaver_rate":{"type":"number","exclusiveMaximum":1.0,"minimum":0.0,"title":"Kiwisaver Rate","description":"Employee contribution as a DECIMAL, 0.035 for 3.5%. Zero by default, which matches the website page. Setting it means the target take-home is AFTER KiwiSaver, so the gross returned is higher.","default":0.0},"has_student_loan":{"type":"boolean","title":"Has Student Loan","description":"Whether repayments come out before the target is reached.","default":false}},"type":"object","required":["target_net"],"title":"NetToGrossRequest","example":{"has_student_loan":false,"kiwisaver_rate":0.0,"period":"weekly","target_net":1200}},"NetToGrossResponse":{"properties":{"result":{"$ref":"#/components/schemas/NetToGrossResult","description":"The gross needed and how it breaks down."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"NetToGrossResponse","example":{"disclaimer":"Estimate only. The target is treated as after income tax and the ACC earner levy, plus any KiwiSaver or student loan you asked for, and nothing else. No tax credits are applied. Not tax advice.","result":{"acc_levy":1402.08,"deductions_included":["income tax","ACC earner levy"],"effective_deduction_rate":22.12,"gross_annual":80118.77,"gross_per_period":1540.75,"income_tax":16316.69,"kiwisaver_employee":0.0,"net_annual":62400.0,"net_per_period":1200.0,"period":"weekly","student_loan":0.0,"target_net_annual":62400.0,"tax_year":"2026/27"}}},"NetToGrossResult":{"properties":{"target_net_annual":{"type":"number","title":"Target Net Annual","description":"The target, annualised."},"gross_annual":{"type":"number","title":"Gross Annual","description":"Gross salary needed, a year."},"income_tax":{"type":"number","title":"Income Tax","description":"PAYE income tax at that gross."},"acc_levy":{"type":"number","title":"Acc Levy","description":"ACC earner levy, capped at the liable earnings maximum."},"kiwisaver_employee":{"type":"number","title":"Kiwisaver Employee","description":"Employee KiwiSaver, zero unless a rate was given."},"student_loan":{"type":"number","title":"Student Loan","description":"Student loan repayment, zero unless requested."},"net_annual":{"type":"number","title":"Net Annual","description":"Take-home at that gross. Equals the target, to the cent."},"period":{"type":"string","title":"Period","description":"The period the per-period figures are in."},"gross_per_period":{"type":"number","title":"Gross Per Period","description":"Gross in the requested period."},"net_per_period":{"type":"number","title":"Net Per Period","description":"Net in the requested period."},"effective_deduction_rate":{"type":"number","title":"Effective Deduction Rate","description":"Everything deducted as a percentage of gross."},"deductions_included":{"items":{"type":"string"},"type":"array","title":"Deductions Included","description":"Exactly which deductions stand between the gross and the target. The answer is meaningless without this, because 'take-home' means different things to different people."},"tax_year":{"type":"string","title":"Tax Year","description":"Tax year the rates are for."}},"type":"object","required":["target_net_annual","gross_annual","income_tax","acc_levy","kiwisaver_employee","student_loan","net_annual","period","gross_per_period","net_per_period","effective_deduction_rate","deductions_included","tax_year"],"title":"NetToGrossResult"},"PAYERequest":{"properties":{"annual_income":{"type":"number","maximum":10000000.0,"minimum":0.0,"title":"Annual Income","description":"Gross annual salary in NZD","examples":[85000]},"kiwisaver_rate":{"type":"number","title":"Kiwisaver Rate","description":"Employee KiwiSaver contribution rate. Valid values: 0 (opted out), 0.03, 0.035, 0.04, 0.06, 0.08, 0.10. Minimum rose to 3.5% from 1 April 2026 for new enrollees.","default":0.035,"examples":[0.035]},"has_student_loan":{"type":"boolean","title":"Has Student Loan","description":"True if the person is repaying a NZ student loan","default":false},"claim_ietc":{"type":"boolean","title":"Claim Ietc","description":"True if eligible for the Independent Earner Tax Credit. Set False for recipients of main benefits, Working for Families Tax Credits, NZ Super, or non-residents.","default":true}},"type":"object","required":["annual_income"],"title":"PAYERequest","example":{"annual_income":90000,"claim_ietc":false,"has_student_loan":false,"kiwisaver_rate":0.03}},"PAYEResponse":{"properties":{"result":{"$ref":"#/components/schemas/PAYEResultBlock","description":"Deductions and take-home pay."},"assumptions":{"$ref":"#/components/schemas/Assumptions","description":"The rates this calculation used. Returned on every response so a stored result can be audited later against the rules of the day."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","assumptions","disclaimer"],"title":"PAYEResponse","example":{"assumptions":{"acc_levy_rate":0.0175,"kiwisaver_min_rate":0.035,"student_loan_rate":0.12,"student_loan_threshold":24128.0,"tax_year":"2026/27"},"disclaimer":"Estimate only based on standard PAYE rules. Not financial or tax advice. Does not account for secondary income, ESCT differences, or non-resident status.","result":{"acc_levy":1575.0,"effective_tax_rate":23.5,"gross_annual":90000.0,"ietc_credit":0.0,"income_tax":19577.5,"kiwisaver_employee":2700.0,"marginal_tax_rate":33.0,"student_loan":0.0,"take_home_annual":66147.5,"take_home_fortnightly":2544.13,"take_home_weekly":1272.07,"total_deductions":23852.5}}},"PAYEResultBlock":{"properties":{"gross_annual":{"type":"number","title":"Gross Annual","description":"Salary before any deductions, in NZD."},"income_tax":{"type":"number","title":"Income Tax","description":"PAYE income tax for the year, across the progressive brackets."},"acc_levy":{"type":"number","title":"Acc Levy","description":"ACC earners' levy, charged on income up to the annual maximum liable earnings. Separate from income tax."},"kiwisaver_employee":{"type":"number","title":"Kiwisaver Employee","description":"Your KiwiSaver contribution, deducted from gross pay. The employer contribution is not shown here because it does not affect take-home pay."},"student_loan":{"type":"number","title":"Student Loan","description":"Student loan repayment on income above the threshold. Zero if not repaying."},"ietc_credit":{"type":"number","title":"Ietc Credit","description":"Independent Earner Tax Credit applied, which reduces tax. Zero when claim_ietc is false or income is outside the eligible band."},"total_deductions":{"type":"number","title":"Total Deductions","description":"Income tax plus ACC plus KiwiSaver plus student loan, less any IETC."},"take_home_annual":{"type":"number","title":"Take Home Annual","description":"Net pay for the year, gross less total deductions."},"take_home_fortnightly":{"type":"number","title":"Take Home Fortnightly","description":"Annual take-home divided by 26."},"take_home_weekly":{"type":"number","title":"Take Home Weekly","description":"Annual take-home divided by 52."},"effective_tax_rate":{"type":"number","title":"Effective Tax Rate","description":"Income tax plus ACC levy, less any IETC, as a percentage of gross. KiwiSaver and student loan are deliberately excluded because they are not tax: one is your own savings and the other repays a debt. So this is NOT total_deductions divided by gross, and on the example below it is 23.5% where that figure would be 26.5%."},"marginal_tax_rate":{"type":"number","title":"Marginal Tax Rate","description":"Income tax rate on the next dollar earned, as a percentage."}},"type":"object","required":["gross_annual","income_tax","acc_levy","kiwisaver_employee","student_loan","ietc_credit","total_deductions","take_home_annual","take_home_fortnightly","take_home_weekly","effective_tax_rate","marginal_tax_rate"],"title":"PAYEResultBlock"},"ParentalLeaveRequest":{"properties":{"annual_income":{"type":"number","minimum":0.0,"title":"Annual Income","description":"Gross annual income before tax, in NZD."},"employment_type":{"type":"string","enum":["employee","self_employed"],"title":"Employment Type","description":"Only a self-employed person gets the statutory weekly minimum.","default":"employee"},"hours_per_week":{"type":"number","minimum":0.0,"title":"Hours Per Week","description":"Average hours a week. Under 10 fails eligibility.","default":40},"weeks_worked":{"type":"integer","minimum":0.0,"title":"Weeks Worked","description":"Weeks worked in the 52 before the due date. Under 26 fails eligibility.","default":52},"weeks_of_leave":{"type":"integer","maximum":26.0,"minimum":0.0,"title":"Weeks Of Leave","description":"Weeks of the 26 week entitlement taken. The balance goes to a partner.","default":26},"kiwisaver_opt_in":{"type":"boolean","title":"Kiwisaver Opt In","description":"Contributions during leave are OPT IN. Doing nothing contributes nothing.","default":false},"kiwisaver_rate":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Kiwisaver Rate","description":"Employee rate as a decimal.","default":0.035}},"type":"object","required":["annual_income"],"title":"ParentalLeaveRequest","example":{"annual_income":80000,"employment_type":"employee","hours_per_week":40,"kiwisaver_opt_in":true,"weeks_of_leave":26,"weeks_worked":52}},"ParentalLeaveResponse":{"properties":{"result":{"$ref":"#/components/schemas/ParentalLeaveResult","description":"The payment, and the shortfall against usual pay."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this estimate."}},"type":"object","required":["result","disclaimer"],"title":"ParentalLeaveResponse","example":{"disclaimer":"Estimate only. Eligibility and payment are set by the Parental Leave and Employment Protection Act and administered by IRD, whose assessment is the one that counts. Does not cover preterm baby payments, keeping in touch hours, or transfers between partners. Not legal advice.","result":{"annual_income":80000.0,"capped_at_maximum":true,"eligible":true,"fortnightly_payment":1622.1,"ineligible_reason":"","kiwisaver_employee_weekly":28.39,"kiwisaver_employer_weekly":28.39,"kiwisaver_opted_in":true,"kiwisaver_total_over_leave":1476.11,"ordinary_weekly_pay":1538.46,"self_employed_minimum_applied":false,"total_gap":18912.7,"total_payment":21087.3,"weekly_gap":727.41,"weekly_payment":811.05,"weeks_available_for_partner":0,"weeks_of_leave":26}}},"ParentalLeaveResult":{"properties":{"eligible":{"type":"boolean","title":"Eligible","description":"Whether both statutory tests are met."},"ineligible_reason":{"type":"string","title":"Ineligible Reason","description":"Which test failed, and by how much. Empty when eligible."},"annual_income":{"type":"number","title":"Annual Income","description":"Income you sent."},"ordinary_weekly_pay":{"type":"number","title":"Ordinary Weekly Pay","description":"Usual weekly pay, income divided by 52."},"weekly_payment":{"type":"number","title":"Weekly Payment","description":"Weekly parental leave payment. Zero if not eligible."},"fortnightly_payment":{"type":"number","title":"Fortnightly Payment","description":"Twice the weekly payment."},"capped_at_maximum":{"type":"boolean","title":"Capped At Maximum","description":"True when usual pay exceeds the statutory cap."},"self_employed_minimum_applied":{"type":"boolean","title":"Self Employed Minimum Applied","description":"True when the self-employed floor lifted the payment."},"weeks_of_leave":{"type":"integer","title":"Weeks Of Leave","description":"Weeks taken."},"weeks_available_for_partner":{"type":"integer","title":"Weeks Available For Partner","description":"The rest of the 26 week entitlement."},"total_payment":{"type":"number","title":"Total Payment","description":"Payment across the whole leave."},"weekly_gap":{"type":"number","title":"Weekly Gap","description":"Usual weekly pay less the payment. For anyone over about $42,000 this is the number that matters, not the payment itself."},"total_gap":{"type":"number","title":"Total Gap","description":"The shortfall across the whole leave period."},"kiwisaver_opted_in":{"type":"boolean","title":"Kiwisaver Opted In","description":"Whether contributions continue."},"kiwisaver_employee_weekly":{"type":"number","title":"Kiwisaver Employee Weekly","description":"Your weekly contribution, if opted in."},"kiwisaver_employer_weekly":{"type":"number","title":"Kiwisaver Employer Weekly","description":"Employer weekly contribution, if opted in."},"kiwisaver_total_over_leave":{"type":"number","title":"Kiwisaver Total Over Leave","description":"Both contributions across the leave."}},"type":"object","required":["eligible","ineligible_reason","annual_income","ordinary_weekly_pay","weekly_payment","fortnightly_payment","capped_at_maximum","self_employed_minimum_applied","weeks_of_leave","weeks_available_for_partner","total_payment","weekly_gap","total_gap","kiwisaver_opted_in","kiwisaver_employee_weekly","kiwisaver_employer_weekly","kiwisaver_total_over_leave"],"title":"ParentalLeaveResult"},"PowerTowerRequest":{"properties":{"base":{"type":"number","minimum":0.0,"title":"Base","description":"The number being raised."},"height":{"type":"integer","maximum":10.0,"minimum":0.0,"title":"Height","description":"How many times it appears in the tower. Capped at 10 because it overflows almost immediately."}},"type":"object","required":["base","height"],"title":"PowerTowerRequest","example":{"base":2,"height":4}},"PowerTowerResponse":{"properties":{"result":{"$ref":"#/components/schemas/PowerTowerResultModel","description":"The tower's value."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"PowerTowerResponse","example":{"disclaimer":"Evaluated in double precision floating point, so large values lose accuracy before they overflow.","result":{"base":2.0,"expression":"2^2^2^2  (evaluated right to left)","height":4,"is_finite":true,"note":"Evaluated right to left, so a^^3 is a^(a^a) and not (a^a)^a. Those are different numbers.","value":65536.0}}},"PowerTowerResultModel":{"properties":{"base":{"type":"number","title":"Base","description":"Base you sent."},"height":{"type":"integer","title":"Height","description":"Height you sent."},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"The value, or null when the result is too large to represent."},"is_finite":{"type":"boolean","title":"Is Finite","description":"False when the result overflowed."},"expression":{"type":"string","title":"Expression","description":"The tower written out."},"note":{"type":"string","title":"Note","description":"How it was evaluated, or why there is no value."}},"type":"object","required":["base","height","is_finite","expression","note"],"title":"PowerTowerResultModel"},"ProRataRequest":{"properties":{"full_time_salary":{"type":"number","minimum":0.0,"title":"Full Time Salary","description":"The advertised full-time annual salary."},"full_time_hours":{"type":"number","exclusiveMinimum":0.0,"title":"Full Time Hours","description":"Hours a week the full-time role is based on.","default":40.0},"your_hours":{"type":"number","minimum":0.0,"title":"Your Hours","description":"Hours a week actually worked.","default":20.0},"kiwisaver_rate":{"type":"number","exclusiveMaximum":1.0,"minimum":0.0,"title":"Kiwisaver Rate","description":"Employee contribution as a DECIMAL.","default":0.035},"has_student_loan":{"type":"boolean","title":"Has Student Loan","description":"Whether repayments are deducted.","default":false},"claim_ietc":{"type":"boolean","title":"Claim Ietc","description":"Whether the Independent Earner Tax Credit applies. Part-time earnings are exactly where it is worth the most, so it defaults on.","default":true}},"type":"object","required":["full_time_salary"],"title":"ProRataRequest","example":{"claim_ietc":true,"full_time_hours":40,"full_time_salary":90000,"has_student_loan":false,"kiwisaver_rate":0.035,"your_hours":24}},"ProRataResponse":{"properties":{"result":{"$ref":"#/components/schemas/ProRataResult","description":"Gross and net at the reduced hours."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"ProRataResponse","example":{"disclaimer":"Estimate only. Assumes the salary scales strictly with hours, which an employment agreement may not. Take-home uses current year rates and the assumptions you gave. Not financial or employment advice.","result":{"acc_levy":945.0,"fortnightly":2076.92,"fraction_of_full_time":60.0,"full_time_hours":40.0,"full_time_salary":90000.0,"hourly_rate":43.27,"income_tax":8420.5,"kiwisaver_employee":1890.0,"monthly":4500.0,"pro_rata_annual":54000.0,"student_loan":0.0,"take_home_annual":43264.5,"take_home_weekly":832.01,"tax_year":"2026/27","weekly":1038.46,"your_hours":24.0}}},"ProRataResult":{"properties":{"full_time_salary":{"type":"number","title":"Full Time Salary","description":"Full-time salary as given."},"full_time_hours":{"type":"number","title":"Full Time Hours","description":"Full-time hours a week."},"your_hours":{"type":"number","title":"Your Hours","description":"Hours a week worked."},"fraction_of_full_time":{"type":"number","title":"Fraction Of Full Time","description":"Hours as a percentage of full time."},"pro_rata_annual":{"type":"number","title":"Pro Rata Annual","description":"The salary at those hours, gross."},"hourly_rate":{"type":"number","title":"Hourly Rate","description":"Implied hourly rate, from the full-time salary over full-time hours times 52. The same number either way round."},"monthly":{"type":"number","title":"Monthly","description":"Gross a month."},"fortnightly":{"type":"number","title":"Fortnightly","description":"Gross a fortnight."},"weekly":{"type":"number","title":"Weekly","description":"Gross a week."},"take_home_annual":{"type":"number","title":"Take Home Annual","description":"After PAYE, ACC, KiwiSaver and student loan."},"take_home_weekly":{"type":"number","title":"Take Home Weekly","description":"Take-home a week."},"income_tax":{"type":"number","title":"Income Tax","description":"PAYE income tax on the pro rata salary."},"acc_levy":{"type":"number","title":"Acc Levy","description":"ACC earner levy."},"kiwisaver_employee":{"type":"number","title":"Kiwisaver Employee","description":"Employee KiwiSaver contribution."},"student_loan":{"type":"number","title":"Student Loan","description":"Student loan repayment."},"tax_year":{"type":"string","title":"Tax Year","description":"Tax year the rates are for."}},"type":"object","required":["full_time_salary","full_time_hours","your_hours","fraction_of_full_time","pro_rata_annual","hourly_rate","monthly","fortnightly","weekly","take_home_annual","take_home_weekly","income_tax","acc_levy","kiwisaver_employee","student_loan","tax_year"],"title":"ProRataResult"},"RateRecord":{"properties":{"id":{"type":"string","title":"Id","description":"Stable identifier. Safe to store and to key on."},"label":{"type":"string","title":"Label","description":"What the figure is, in words."},"value":{"type":"string","title":"Value","description":"The current value, as published. A string so 1.75 and 0.0175 are never confused by a float."},"effective_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effective From","description":"ISO date the value took effect, where the source states one."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Where it was read from. A URL for anything verified against an issuing body."},"verified_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verified On","description":"ISO date this figure was last checked against the issuing body. NULL means recorded but not yet verified, and is deliberately visible rather than hidden."},"review_cycle":{"type":"string","title":"Review Cycle","description":"When it next changes: annual-1-april, budget-may, periodic, or on-legislative-change. This is the field to filter on if you want to know what to re-check and when."},"previous_values":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Previous Values","description":"Prior values, most recent first. Undated for now."},"history_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"History Note","description":"The limits of previous_values."},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Anything a consumer needs to know about this figure."}},"type":"object","required":["id","label","value","review_cycle"],"title":"RateRecord"},"RatesResponse":{"properties":{"dataset":{"type":"string","title":"Dataset","description":"Name of the dataset."},"publisher":{"type":"string","title":"Publisher","description":"Who maintains it."},"count":{"type":"integer","title":"Count","description":"Rates returned by this request."},"total":{"type":"integer","title":"Total","description":"Rates in the dataset overall."},"verified_count":{"type":"integer","title":"Verified Count","description":"How many carry a verification date."},"register_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Updated","description":"When the register was last touched."},"correctness_note":{"type":"string","title":"Correctness Note","description":"How these figures are checked."},"rates":{"items":{"$ref":"#/components/schemas/RateRecord"},"type":"array","title":"Rates","description":"The rates themselves."}},"type":"object","required":["dataset","publisher","count","total","verified_count","correctness_note","rates"],"title":"RatesResponse"},"RedundancyEntitlementRequest":{"properties":{"annual_salary":{"type":"number","minimum":0.0,"title":"Annual Salary","description":"Gross annual salary."},"years_of_service":{"type":"integer","minimum":0.0,"title":"Years Of Service","description":"Completed years. Part years are not counted.","default":0},"notice_weeks":{"type":"integer","minimum":0.0,"title":"Notice Weeks","description":"Notice period in weeks.","default":4},"notice_worked":{"type":"boolean","title":"Notice Worked","description":"True if the notice period is worked, false if paid in lieu. It changes where the money appears, not how much there is.","default":true},"annual_leave_days":{"type":"number","minimum":0.0,"title":"Annual Leave Days","description":"Days of annual leave accrued and not taken.","default":0.0},"alternative_holiday_days":{"type":"number","minimum":0.0,"title":"Alternative Holiday Days","description":"Alternative holidays ('days in lieu') not taken.","default":0.0},"redundancy_clause":{"type":"string","enum":["none","2_weeks","3_weeks","4_weeks","fixed_4","fixed_8","fixed_13","custom"],"title":"Redundancy Clause","description":"What the employment agreement provides. Default is none, because New Zealand has no statutory redundancy pay.","default":"none"},"custom_redundancy_amount":{"type":"number","minimum":0.0,"title":"Custom Redundancy Amount","description":"Used only when redundancy_clause is 'custom'.","default":0.0},"outstanding_wages":{"type":"number","minimum":0.0,"title":"Outstanding Wages","description":"Wages worked and not yet paid.","default":0.0}},"type":"object","required":["annual_salary"],"title":"RedundancyEntitlementRequest","example":{"alternative_holiday_days":2,"annual_leave_days":12,"annual_salary":85000,"custom_redundancy_amount":0,"notice_weeks":4,"notice_worked":true,"outstanding_wages":1500,"redundancy_clause":"2_weeks","years_of_service":8}},"RedundancyEntitlementResponse":{"properties":{"result":{"$ref":"#/components/schemas/RedundancyEntitlementResult","description":"Gross entitlements on redundancy."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"RedundancyEntitlementResponse","example":{"disclaimer":"All figures are GROSS. New Zealand has no statutory redundancy pay, so compensation depends entirely on the employment agreement. This is a guide to what to check, not employment law advice.","result":{"alternative_holiday_days":2.0,"alternative_holiday_payout":653.85,"annual_leave_days":12.0,"annual_leave_payout":3923.08,"annual_salary":85000.0,"daily_pay":326.92,"excludes":["Tax. Every figure is gross.","The 8% of gross alternative for under a year of service","Averaged pay for variable or irregular hours","Part years of service","Any garden leave or restraint of trade payment"],"notes":["Notice is being worked, so notice_payout is nil and the notice wages arrive as ordinary salary. total_all_in already includes them; total_package does not, because it is the final pay.","All figures are GROSS. Redundancy compensation is an extra pay taxed at the lump sum rate, and holiday pay in a final pay has its own rules."],"notice_payout":0.0,"notice_wages":6538.46,"notice_weeks":4,"notice_worked":true,"outstanding_wages":1500.0,"redundancy_clause":"2_weeks","redundancy_clause_label":"2 weeks per year of service (16 weeks)","redundancy_compensation":26153.85,"statutory_position":"New Zealand has no statutory redundancy pay. Compensation is owed only if the employment agreement provides for it. The mandatory entitlements below are owed regardless.","total_all_in":38769.23,"total_mandatory":6076.92,"total_package":32230.77,"weekly_pay":1634.62,"years_of_service":8}}},"RedundancyEntitlementResult":{"properties":{"annual_salary":{"type":"number","title":"Annual Salary","description":"Salary as given."},"weekly_pay":{"type":"number","title":"Weekly Pay","description":"Salary divided by 52."},"daily_pay":{"type":"number","title":"Daily Pay","description":"Salary divided by 260 working days."},"years_of_service":{"type":"integer","title":"Years Of Service","description":"Completed years as given."},"outstanding_wages":{"type":"number","title":"Outstanding Wages","description":"Unpaid wages as given."},"annual_leave_days":{"type":"number","title":"Annual Leave Days","description":"Annual leave days as given."},"annual_leave_payout":{"type":"number","title":"Annual Leave Payout","description":"Annual leave days at the daily rate."},"alternative_holiday_days":{"type":"number","title":"Alternative Holiday Days","description":"Alternative holidays as given."},"alternative_holiday_payout":{"type":"number","title":"Alternative Holiday Payout","description":"Alternative holidays at the daily rate."},"notice_weeks":{"type":"integer","title":"Notice Weeks","description":"Notice period as given."},"notice_worked":{"type":"boolean","title":"Notice Worked","description":"Whether notice is worked."},"notice_wages":{"type":"number","title":"Notice Wages","description":"Pay for the notice period. Received either way."},"notice_payout":{"type":"number","title":"Notice Payout","description":"The part of the notice that lands in the final pay. Nil when the notice is worked, because it arrives as ordinary salary instead."},"total_mandatory":{"type":"number","title":"Total Mandatory","description":"What is owed by law: wages, leave, alternative holidays, notice in lieu."},"redundancy_clause":{"type":"string","title":"Redundancy Clause","description":"Clause as given."},"redundancy_clause_label":{"type":"string","title":"Redundancy Clause Label","description":"The clause in words."},"redundancy_compensation":{"type":"number","title":"Redundancy Compensation","description":"Contractual redundancy pay. Zero unless a clause provides for it."},"total_package":{"type":"number","title":"Total Package","description":"The final pay: mandatory plus compensation."},"total_all_in":{"type":"number","title":"Total All In","description":"Everything received, wherever it is paid from. The same figure whether notice is worked or paid in lieu. Quote this one when somebody asks what they will get."},"statutory_position":{"type":"string","title":"Statutory Position","description":"The New Zealand position on redundancy pay, in words."},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"What applied to this case."},"excludes":{"items":{"type":"string"},"type":"array","title":"Excludes","description":"What this deliberately does not do."}},"type":"object","required":["annual_salary","weekly_pay","daily_pay","years_of_service","outstanding_wages","annual_leave_days","annual_leave_payout","alternative_holiday_days","alternative_holiday_payout","notice_weeks","notice_worked","notice_wages","notice_payout","total_mandatory","redundancy_clause","redundancy_clause_label","redundancy_compensation","total_package","total_all_in","statutory_position","notes","excludes"],"title":"RedundancyEntitlementResult"},"RoadUserChargesRequest":{"properties":{"annual_km":{"type":"number","minimum":0.0,"title":"Annual Km","description":"Distance driven in a year."},"vehicle_type":{"type":"string","title":"Vehicle Type","description":"ev, diesel, phev_petrol, phev_diesel or hybrid_petrol. A PETROL plug-in hybrid pays about half; a DIESEL one pays the full rate. An ordinary petrol hybrid pays no RUC at all.","default":"diesel"},"block_size_km":{"type":"number","exclusiveMinimum":0.0,"title":"Block Size Km","description":"Size of each RUC purchase. Larger blocks mean fewer transaction fees, which is the main lever a driver has.","default":5000},"purchase_method":{"type":"string","title":"Purchase Method","description":"online or agent. The transaction fee differs.","default":"online"},"fuel_efficiency_l_per_100km":{"type":"number","minimum":0.0,"title":"Fuel Efficiency L Per 100Km","description":"Used only for the petrol excise comparison, never for the RUC itself.","default":8.0}},"type":"object","required":["annual_km"],"title":"RoadUserChargesRequest","example":{"annual_km":11500,"block_size_km":5000,"fuel_efficiency_l_per_100km":8.0,"purchase_method":"online","vehicle_type":"diesel"}},"RoadUserChargesResponse":{"properties":{"result":{"$ref":"#/components/schemas/RoadUserChargesResult","description":"Annual cost and its parts."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"RoadUserChargesResponse","example":{"disclaimer":"Indicative. Light vehicles 3,500 kg and under at NZTA rates confirmed 29 August 2026; heavy vehicle rates run to over a hundred type and weight combinations and are not covered here.","result":{"admin_fee_each":12.44,"admin_total":37.32,"annual_km":11500.0,"block_size_km":5000.0,"cost_per_km_cents":7.92,"difference_against_petrol":267.32,"fuel_efficiency_l_per_100km":8.0,"note":"Bought in 5,000 km blocks, that is 3 transaction(s) a year at 12.44 each. Larger blocks mean fewer fees.","pays_ruc":true,"petrol_equivalent_excise":644.0,"provenance":{"petrol_excise_per_litre":"0.70, used only for the comparison figure, not for any RUC amount","ruc_rate":"NZ Transport Agency, light vehicles 3,500 kg and under, confirmed 29 August 2026","transaction_fees":"NZ Transport Agency, confirmed 29 August 2026: $12.44 online or through the NZTA app, $13.71 at an agent counter"},"ruc_charge":874.0,"ruc_rate_per_1000km":76.0,"tax_year":"2026/27","total_annual_cost":911.32,"transactions":3,"vehicle_label":"Light diesel, under 3,500 kg","vehicle_type":"diesel"}}},"RoadUserChargesResult":{"properties":{"vehicle_type":{"type":"string","title":"Vehicle Type","description":"Vehicle type as given."},"vehicle_label":{"type":"string","title":"Vehicle Label","description":"What that type means."},"pays_ruc":{"type":"boolean","title":"Pays Ruc","description":"False for an ordinary petrol hybrid."},"ruc_rate_per_1000km":{"type":"number","title":"Ruc Rate Per 1000Km","description":"The rate charged per 1,000 km."},"annual_km":{"type":"number","title":"Annual Km","description":"Distance as given."},"ruc_charge":{"type":"number","title":"Ruc Charge","description":"The charge itself, before fees."},"block_size_km":{"type":"number","title":"Block Size Km","description":"Purchase block size used."},"transactions":{"type":"integer","title":"Transactions","description":"Purchases needed in a year."},"admin_fee_each":{"type":"number","title":"Admin Fee Each","description":"Transaction fee per purchase."},"admin_total":{"type":"number","title":"Admin Total","description":"Fees for the year. A naive distance-times-rate calculation misses this entirely, and at small block sizes it is not small."},"total_annual_cost":{"type":"number","title":"Total Annual Cost","description":"Charge plus fees."},"cost_per_km_cents":{"type":"number","title":"Cost Per Km Cents","description":"Effective cost in cents per kilometre."},"petrol_equivalent_excise":{"type":"number","title":"Petrol Equivalent Excise","description":"What a petrol vehicle would pay in excise over the same distance."},"difference_against_petrol":{"type":"number","title":"Difference Against Petrol","description":"Positive means the RUC vehicle pays more."},"fuel_efficiency_l_per_100km":{"type":"number","title":"Fuel Efficiency L Per 100Km","description":"Efficiency used for the comparison."},"note":{"type":"string","title":"Note","description":"The transaction arithmetic, or why no RUC is due."},"provenance":{"additionalProperties":true,"type":"object","title":"Provenance","description":"Which figures are confirmed against NZTA and which are not. The rate is; the transaction fees are not."},"tax_year":{"type":"string","title":"Tax Year","description":"Year the rates are for."}},"type":"object","required":["vehicle_type","vehicle_label","pays_ruc","ruc_rate_per_1000km","annual_km","ruc_charge","block_size_km","transactions","admin_fee_each","admin_total","total_annual_cost","cost_per_km_cents","petrol_equivalent_excise","difference_against_petrol","fuel_efficiency_l_per_100km","note","provenance","tax_year"],"title":"RoadUserChargesResult"},"SecondaryTaxRequest":{"properties":{"main_income":{"type":"number","minimum":0.0,"title":"Main Income","description":"Gross annual income from the main job."},"secondary_amount":{"type":"number","minimum":0.0,"title":"Secondary Amount","description":"The second income, in the frequency given."},"secondary_frequency":{"type":"string","title":"Secondary Frequency","description":"annual, monthly, fortnightly or weekly.","default":"annual"},"has_student_loan":{"type":"boolean","title":"Has Student Loan","description":"Whether a student loan is being repaid. This changes the code to its SL variant and adds 12 points to the flat rate.","default":false}},"type":"object","required":["main_income","secondary_amount"],"title":"SecondaryTaxRequest","example":{"has_student_loan":false,"main_income":70000,"secondary_amount":15000,"secondary_frequency":"annual"}},"SecondaryTaxResponse":{"properties":{"result":{"$ref":"#/components/schemas/SecondaryTaxResult","description":"The code, the deduction and the square-up."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"SecondaryTaxResponse","example":{"disclaimer":"Estimate only, covering these two income sources. The year-end position ignores other income, tax credits and any tailored tax rate. Codes and rates are IRD IR330 as at 1 April 2026. Not tax advice.","result":{"acc_component_percent":1.75,"bracket":"$78,101 to $180,000","flat_rate_percent":34.75,"income_tax_component_percent":33.0,"main_acc_levy":1225.0,"main_income":70000.0,"main_income_tax":13220.5,"main_student_loan":0.0,"secondary_income_annual":15000.0,"secondary_net":9787.5,"secondary_paye":5212.5,"student_loan_component_percent":0.0,"tax_code":"ST","tax_year":"2026/27","total_deducted":19658.0,"total_income":85000.0,"total_owed_on_combined":19415.0,"year_end_difference":-243.0,"year_end_position":"refund"}}},"SecondaryTaxResult":{"properties":{"main_income":{"type":"number","title":"Main Income","description":"Main job income as given."},"secondary_income_annual":{"type":"number","title":"Secondary Income Annual","description":"Second income, annualised."},"total_income":{"type":"number","title":"Total Income","description":"Both together, which selects the code."},"tax_code":{"type":"string","title":"Tax Code","description":"The IR330 secondary code: SB, S, SH, ST or SA, with SL if applicable."},"flat_rate_percent":{"type":"number","title":"Flat Rate Percent","description":"The rate deducted from the whole second income."},"income_tax_component_percent":{"type":"number","title":"Income Tax Component Percent","description":"The income tax part of that rate."},"acc_component_percent":{"type":"number","title":"Acc Component Percent","description":"The ACC earner levy inside the rate. This is why a secondary rate is not comparable with an ordinary income tax rate."},"student_loan_component_percent":{"type":"number","title":"Student Loan Component Percent","description":"The student loan repayment part, zero without a loan."},"bracket":{"type":"string","title":"Bracket","description":"Combined income band the code comes from."},"secondary_paye":{"type":"number","title":"Secondary Paye","description":"Deducted from the second income in a year."},"secondary_net":{"type":"number","title":"Secondary Net","description":"What is left of the second income."},"main_income_tax":{"type":"number","title":"Main Income Tax","description":"Income tax on the main job."},"main_acc_levy":{"type":"number","title":"Main Acc Levy","description":"ACC levy on the main job."},"main_student_loan":{"type":"number","title":"Main Student Loan","description":"Student loan on the main job."},"total_owed_on_combined":{"type":"number","title":"Total Owed On Combined","description":"What is actually owed on both incomes together."},"total_deducted":{"type":"number","title":"Total Deducted","description":"What the two employers will have deducted."},"year_end_difference":{"type":"number","title":"Year End Difference","description":"Owed minus deducted. Positive is a bill, negative is a refund. A refund here is normal and is the answer to 'is secondary tax a rip off'."},"year_end_position":{"type":"string","title":"Year End Position","description":"square, bill or refund."},"tax_year":{"type":"string","title":"Tax Year","description":"Tax year the codes and rates are for."}},"type":"object","required":["main_income","secondary_income_annual","total_income","tax_code","flat_rate_percent","income_tax_component_percent","acc_component_percent","student_loan_component_percent","bracket","secondary_paye","secondary_net","main_income_tax","main_acc_levy","main_student_loan","total_owed_on_combined","total_deducted","year_end_difference","year_end_position","tax_year"],"title":"SecondaryTaxResult"},"TaxRefundRequest":{"properties":{"gross_income":{"type":"number","minimum":0.0,"title":"Gross Income","description":"Total gross income for the year, before tax, in NZD."},"tax_year":{"type":"string","enum":["2026-27","2025-26","2024-25","2023-24"],"title":"Tax Year","description":"Which year's rules to apply. 2024-25 is a composite year: the thresholds moved on 31 July 2024, so IRD blended rates apply and the result is approximate, which the response flags.","default":"2026-27"},"paye_deducted":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Paye Deducted","description":"Total PAYE deducted across the whole year, from your payslips or IRD summary. Omit to estimate it from tax_code and months_worked instead, which is less accurate but needs nothing from IRD."},"acc_included_in_paye":{"type":"boolean","title":"Acc Included In Paye","description":"Whether paye_deducted includes the ACC earner levy. Most payslips lump them together. ACC is not income tax, so leaving it in would invent a refund of up to $2,741 that does not exist.","default":true},"tax_code":{"type":"string","enum":["M","ME","MSL","SB","S","SH","ST"],"title":"Tax Code","description":"Primary tax code. Only used when paye_deducted is omitted.","default":"M"},"months_worked":{"type":"number","maximum":12.0,"exclusiveMinimum":0.0,"title":"Months Worked","description":"Months actually worked. This is often the whole refund: PAYE is deducted as though each pay continues all year, so a part year over-deducts.","default":12},"secondary_income":{"type":"number","minimum":0.0,"title":"Secondary Income","description":"Income from a second job taxed on a secondary code.","default":0},"secondary_tax_code":{"type":"string","enum":["SB","S","SH","ST"],"title":"Secondary Tax Code","description":"The second job's tax code.","default":"S"},"donations":{"type":"number","minimum":0.0,"title":"Donations","description":"Donations to approved donee organisations during the year.","default":0},"student_loan_deducted":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Student Loan Deducted","description":"Student loan repayments deducted. Omit if there is no loan."},"ietc_eligible":{"type":"boolean","title":"Ietc Eligible","description":"Whether the Independent Earner Tax Credit applies. Set false for anyone on a main benefit, Working for Families or NZ Super.","default":true}},"type":"object","required":["gross_income"],"title":"TaxRefundRequest","example":{"acc_included_in_paye":true,"gross_income":62000,"months_worked":8,"paye_deducted":12800,"tax_year":"2026-27"}},"TaxRefundResponse":{"properties":{"result":{"$ref":"#/components/schemas/TaxRefundResult","description":"The refund or bill, and where it comes from."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this estimate."}},"type":"object","required":["result","disclaimer"],"title":"TaxRefundResponse","example":{"disclaimer":"Estimate only. IRD issues an automatic income tax assessment for most people and its figure is the one that counts. Salary and wages only: this does not cover self-employed or rental income, Working for Families, or losses carried forward. Not tax advice.","result":{"acc_levy":1085.0,"approximate":false,"correct_tax":10820.5,"donations_claimed":0.0,"donations_credit":0.0,"gross_income":62000.0,"ietc_credit":520.0,"is_refund":true,"months_worked":8.0,"net_tax_due":10300.5,"part_year_over_deducted":2891.17,"paye_credit":11715.0,"paye_deducted":12800.0,"refund_or_bill":1414.5,"secondary_income":0.0,"secondary_over_deducted":0.0,"secondary_tax_paid":0.0,"secondary_tax_true_cost":0.0,"student_loan_deducted":0.0,"student_loan_difference":0.0,"student_loan_due":0.0,"tax_year":"2026-27","tax_year_label":"2026/27"}}},"TaxRefundResult":{"properties":{"tax_year":{"type":"string","title":"Tax Year","description":"The year's rules applied."},"tax_year_label":{"type":"string","title":"Tax Year Label","description":"That year written the way IRD writes it."},"approximate":{"type":"boolean","title":"Approximate","description":"True for 2024-25, where blended rates make the answer approximate."},"gross_income":{"type":"number","title":"Gross Income","description":"Gross income you sent."},"correct_tax":{"type":"number","title":"Correct Tax","description":"Income tax actually owed on that income for the year."},"ietc_credit":{"type":"number","title":"Ietc Credit","description":"Independent Earner Tax Credit applied. Zero if not eligible or outside the band."},"net_tax_due":{"type":"number","title":"Net Tax Due","description":"Tax owed after the IETC. Never below zero."},"acc_levy":{"type":"number","title":"Acc Levy","description":"ACC earner levy for the year, 1.75% of liable earnings up to the cap. Not income tax."},"paye_deducted":{"type":"number","title":"Paye Deducted","description":"PAYE deducted, as given or as estimated."},"paye_credit":{"type":"number","title":"Paye Credit","description":"PAYE counting towards the tax bill, after any ACC has been taken out of it."},"refund_or_bill":{"type":"number","title":"Refund Or Bill","description":"POSITIVE is a refund owed to you, NEGATIVE is tax you owe. The website shows this as a positive number with a separate label, so compare against is_refund rather than the sign on screen."},"is_refund":{"type":"boolean","title":"Is Refund","description":"True when money is owed to you."},"donations_claimed":{"type":"number","title":"Donations Claimed","description":"Donations counted, capped at your income."},"donations_credit":{"type":"number","title":"Donations Credit","description":"A third of donations claimed. Paid separately by IRD on its own form, so it is NOT included in refund_or_bill."},"student_loan_due":{"type":"number","title":"Student Loan Due","description":"12% of income over the annual threshold."},"student_loan_deducted":{"type":"number","title":"Student Loan Deducted","description":"Repayments actually deducted."},"student_loan_difference":{"type":"number","title":"Student Loan Difference","description":"Deducted less due. Positive means overpaid. Settled separately from income tax, so also not in refund_or_bill."},"secondary_income":{"type":"number","title":"Secondary Income","description":"Second job income counted."},"secondary_tax_paid":{"type":"number","title":"Secondary Tax Paid","description":"Flat tax taken on that income by its code."},"secondary_tax_true_cost":{"type":"number","title":"Secondary Tax True Cost","description":"What that income actually cost in tax at your true marginal rate."},"secondary_over_deducted":{"type":"number","title":"Secondary Over Deducted","description":"How much the secondary code over-deducted. This is why a second job so often produces a refund, and it is already inside refund_or_bill rather than being extra."},"months_worked":{"type":"number","title":"Months Worked","description":"Months worked, after clamping to between 0.5 and 12."},"part_year_over_deducted":{"type":"number","title":"Part Year Over Deducted","description":"How much extra came out because PAYE annualised a part year. Usually the largest single reason for a refund. Already inside refund_or_bill."}},"type":"object","required":["tax_year","tax_year_label","approximate","gross_income","correct_tax","ietc_credit","net_tax_due","acc_levy","paye_deducted","paye_credit","refund_or_bill","is_refund","donations_claimed","donations_credit","student_loan_due","student_loan_deducted","student_loan_difference","secondary_income","secondary_tax_paid","secondary_tax_true_cost","secondary_over_deducted","months_worked","part_year_over_deducted"],"title":"TaxRefundResult"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VehicleLoanRequest":{"properties":{"vehicle_price":{"type":"number","minimum":0.0,"title":"Vehicle Price","description":"The price of the vehicle."},"deposit":{"type":"number","minimum":0.0,"title":"Deposit","description":"Cash or trade-in put down up front.","default":0.0},"annual_interest_rate_pct":{"type":"number","minimum":0.0,"title":"Annual Interest Rate Pct","description":"Annual rate as a PERCENTAGE, so 12.95 not 0.1295. Car finance commonly runs well above mortgage rates.","default":12.95},"term_years":{"type":"number","exclusiveMinimum":0.0,"title":"Term Years","description":"Loan term in years.","default":5.0}},"type":"object","required":["vehicle_price"],"title":"VehicleLoanRequest","example":{"annual_interest_rate_pct":12.95,"deposit":5000,"term_years":5,"vehicle_price":35000}},"VehicleLoanResponse":{"properties":{"result":{"$ref":"#/components/schemas/VehicleLoanResult","description":"Repayment and what the interest costs."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"VehicleLoanResponse","example":{"disclaimer":"Excludes establishment and PPSR fees, balloon or residual payments, insurance and dealer add-ons, which are usually financed too, so a real contract's payment is higher. Not financial advice.","result":{"amount_borrowed":30000.0,"annual_interest_rate_pct":12.95,"deposit":5000.0,"deposit_share_of_price":14.29,"excludes":["establishment, administration and PPSR fees, which are usually financed too, so a real contract's payment is higher than this","balloon or residual payments, which cut the monthly figure and leave a lump sum at the end","mechanical breakdown insurance, payment protection and dealer add-ons bundled into the finance","depreciation, which is why a borrower can owe more than the vehicle is worth partway through the term"],"fortnightly_equivalent":314.69,"interest_share_of_borrowing":36.36,"monthly_repayment":681.82,"term_months":60,"term_years":5.0,"total_cost_including_deposit":45909.47,"total_interest":10909.47,"total_repaid":40909.47,"vehicle_price":35000.0,"weekly_equivalent":157.34}}},"VehicleLoanResult":{"properties":{"vehicle_price":{"type":"number","title":"Vehicle Price","description":"Price as given."},"deposit":{"type":"number","title":"Deposit","description":"Deposit as given."},"amount_borrowed":{"type":"number","title":"Amount Borrowed","description":"Price less deposit."},"annual_interest_rate_pct":{"type":"number","title":"Annual Interest Rate Pct","description":"Rate used."},"term_years":{"type":"number","title":"Term Years","description":"Term in years."},"term_months":{"type":"integer","title":"Term Months","description":"Term in whole months."},"monthly_repayment":{"type":"number","title":"Monthly Repayment","description":"The contracted monthly payment."},"fortnightly_equivalent":{"type":"number","title":"Fortnightly Equivalent","description":"The monthly payment converted, not a fortnightly amortisation. Paying fortnightly would clear the loan faster and is a different product."},"weekly_equivalent":{"type":"number","title":"Weekly Equivalent","description":"The monthly payment converted to a week."},"total_repaid":{"type":"number","title":"Total Repaid","description":"Every payment over the term."},"total_interest":{"type":"number","title":"Total Interest","description":"What the borrowing costs."},"total_cost_including_deposit":{"type":"number","title":"Total Cost Including Deposit","description":"Repayments plus the deposit."},"interest_share_of_borrowing":{"type":"number","title":"Interest Share Of Borrowing","description":"Interest as a percentage of the amount borrowed. The figure that shows what a long term at a high rate really costs."},"deposit_share_of_price":{"type":"number","title":"Deposit Share Of Price","description":"Deposit as a percentage of the price."},"excludes":{"items":{"type":"string"},"type":"array","title":"Excludes","description":"Costs a real contract adds that this does not model."}},"type":"object","required":["vehicle_price","deposit","amount_borrowed","annual_interest_rate_pct","term_years","term_months","monthly_repayment","fortnightly_equivalent","weekly_equivalent","total_repaid","total_interest","total_cost_including_deposit","interest_share_of_borrowing","deposit_share_of_price","excludes"],"title":"VehicleLoanResult"},"WorkDayInput":{"properties":{"start":{"type":"string","title":"Start","description":"Start time as \"HH:MM\", 24 hour."},"finish":{"type":"string","title":"Finish","description":"Finish time as \"HH:MM\". If it is at or before the start it is treated as an overnight shift, so 22:00 to 06:00 is eight hours."},"break_minutes":{"type":"integer","minimum":0.0,"title":"Break Minutes","description":"Unpaid break in minutes.","default":0},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"Optional name for the day."}},"type":"object","required":["start","finish"],"title":"WorkDayInput"},"WorkDayResult":{"properties":{"label":{"type":"string","title":"Label","description":"The day's name, or its position."},"start":{"type":"string","title":"Start","description":"Start time as given."},"finish":{"type":"string","title":"Finish","description":"Finish time as given."},"break_minutes":{"type":"integer","title":"Break Minutes","description":"Unpaid break deducted."},"hours":{"type":"number","title":"Hours","description":"Paid hours for the day, after the break."},"overnight":{"type":"boolean","title":"Overnight","description":"True when the shift crossed midnight."}},"type":"object","required":["label","start","finish","break_minutes","hours","overnight"],"title":"WorkDayResult"},"WorkHoursRequest":{"properties":{"days":{"items":{"$ref":"#/components/schemas/WorkDayInput"},"type":"array","minItems":1,"title":"Days","description":"One entry per day worked. Leave days off out entirely."},"hourly_rate":{"type":"number","minimum":0.0,"title":"Hourly Rate","description":"Gross pay per hour. Zero for hours only.","default":0}},"type":"object","required":["days"],"title":"WorkHoursRequest","example":{"days":[{"break_minutes":30,"finish":"17:00","label":"Monday","start":"08:30"},{"break_minutes":30,"finish":"17:00","label":"Tuesday","start":"08:30"},{"break_minutes":30,"finish":"17:00","label":"Wednesday","start":"08:30"},{"break_minutes":45,"finish":"19:30","label":"Thursday","start":"08:30"},{"break_minutes":30,"finish":"15:00","label":"Friday","start":"08:30"}],"hourly_rate":32.5}},"WorkHoursResponse":{"properties":{"result":{"$ref":"#/components/schemas/WorkHoursResult","description":"Hours worked and gross pay."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"WorkHoursResponse","example":{"disclaimer":"Gross hours and pay only. Does not apply overtime or penal rates, public holiday entitlements, or minimum wage checks, and does not deduct tax. Not legal advice.","result":{"annual_pay":68022.5,"days":[{"break_minutes":30,"finish":"17:00","hours":8.0,"label":"Monday","overnight":false,"start":"08:30"},{"break_minutes":30,"finish":"17:00","hours":8.0,"label":"Tuesday","overnight":false,"start":"08:30"},{"break_minutes":30,"finish":"17:00","hours":8.0,"label":"Wednesday","overnight":false,"start":"08:30"},{"break_minutes":45,"finish":"19:30","hours":10.25,"label":"Thursday","overnight":false,"start":"08:30"},{"break_minutes":30,"finish":"15:00","hours":6.0,"label":"Friday","overnight":false,"start":"08:30"}],"days_worked":5,"fortnightly_pay":2616.25,"hourly_rate":32.5,"monthly_pay":5668.54,"total_hours":40.25,"weekly_pay":1308.13}}},"WorkHoursResult":{"properties":{"total_hours":{"type":"number","title":"Total Hours","description":"Paid hours across all days."},"days_worked":{"type":"integer","title":"Days Worked","description":"Days with more than zero hours."},"hourly_rate":{"type":"number","title":"Hourly Rate","description":"Rate applied."},"weekly_pay":{"type":"number","title":"Weekly Pay","description":"Gross pay for these hours."},"fortnightly_pay":{"type":"number","title":"Fortnightly Pay","description":"Twice the weekly figure."},"monthly_pay":{"type":"number","title":"Monthly Pay","description":"A twelfth of the annual figure, not weekly x 4.33."},"annual_pay":{"type":"number","title":"Annual Pay","description":"Weekly pay over 52 weeks, if every week matched."},"days":{"items":{"$ref":"#/components/schemas/WorkDayResult"},"type":"array","title":"Days","description":"Each day, so the total can be checked."}},"type":"object","required":["total_hours","days_worked","hourly_rate","weekly_pay","fortnightly_pay","monthly_pay","annual_pay","days"],"title":"WorkHoursResult"},"WorkingForFamiliesRequest":{"properties":{"children":{"type":"integer","minimum":0.0,"title":"Children","description":"Dependent children in the caregiver's care."},"family_income":{"type":"number","minimum":0.0,"title":"Family Income","description":"Combined gross annual family income from ALL sources: both partners' wages, business income, rental, taxable benefits."},"children_under_3":{"type":"integer","minimum":0.0,"title":"Children Under 3","description":"How many of those children are under 3, for Best Start. IRD pays it until the third birthday, not the first.","default":0},"iwtc_eligible":{"type":"boolean","title":"Iwtc Eligible","description":"Whether the In-Work Tax Credit applies. The test is some income from paid work each week and NOT receiving an income-tested benefit or student allowance. There has been NO hours test since 1 July 2020.","default":true},"best_start_children_first_year_exempt":{"type":"integer","minimum":0.0,"title":"Best Start Children First Year Exempt","description":"How many of the under-3s are in their first year AND were born before 1 April 2026. Those are exempt from the Best Start income test for that year.","default":0},"iwtc_after_march_2027":{"type":"boolean","title":"Iwtc After March 2027","description":"Model the reverted IWTC of $5,070 instead of the temporary $7,670.","default":false}},"type":"object","required":["children","family_income"],"title":"WorkingForFamiliesRequest","example":{"best_start_children_first_year_exempt":0,"children":2,"children_under_3":1,"family_income":85000,"iwtc_after_march_2027":false,"iwtc_eligible":true}},"WorkingForFamiliesResponse":{"properties":{"result":{"$ref":"#/components/schemas/WorkingForFamiliesResult","description":"Entitlement after abatement."},"disclaimer":{"type":"string","title":"Disclaimer","description":"Scope and limits of this calculation."}},"type":"object","required":["result","disclaimer"],"title":"WorkingForFamiliesResponse","example":{"disclaimer":"Estimate using IRD rates effective 1 April 2026. Excludes the Minimum Family Tax Credit, shared care and part-year entitlement. Two figures deliberately differ from the website page and are named in differences_from_website. Confirm your actual payments with IRD.","result":{"abatement":11027.5,"assumptions":{"abatement_rate":0.275,"abatement_threshold":44900.0,"best_start_abatement_rate":0.21,"best_start_abatement_threshold":79000.0,"best_start_annual_per_child":4041.0,"ftc_first_child_annual":7921.0,"ftc_subsequent_child_annual":6454.0,"iwtc_annual":7670.0,"iwtc_is_temporary_rate":true,"source":"Inland Revenue, rates effective 1 April 2026"},"best_start_abatement":1260.0,"best_start_annual":2781.0,"best_start_before_abatement":4041.0,"children":2,"children_under_3":1,"combined_ftc_iwtc_before_abatement":22045.0,"differences_from_website":[],"excludes":["the Minimum Family Tax Credit, which IRD works out separately from the family's tax position rather than its gross income","shared care, which splits entitlement by the share of nights","part-year entitlement and mid-year income changes"],"family_income":85000.0,"ftc_annual":14375.0,"ftc_iwtc_after_abatement":11017.5,"fully_abated":false,"iwtc_annual":7670.0,"iwtc_eligible":true,"tax_year":"2026/27","total_annual":13798.5,"total_fortnightly":530.71,"total_weekly":265.36}}},"WorkingForFamiliesResult":{"properties":{"children":{"type":"integer","title":"Children","description":"Children as given."},"children_under_3":{"type":"integer","title":"Children Under 3","description":"Best Start eligible children."},"family_income":{"type":"number","title":"Family Income","description":"Family income as given."},"ftc_annual":{"type":"number","title":"Ftc Annual","description":"Family Tax Credit before abatement."},"iwtc_annual":{"type":"number","title":"Iwtc Annual","description":"In-Work Tax Credit before abatement, per family."},"iwtc_eligible":{"type":"boolean","title":"Iwtc Eligible","description":"Whether the IWTC was included."},"combined_ftc_iwtc_before_abatement":{"type":"number","title":"Combined Ftc Iwtc Before Abatement","description":"FTC and IWTC together, which is the pool that abates."},"abatement":{"type":"number","title":"Abatement","description":"27.5 cents per dollar of family income above $44,900."},"ftc_iwtc_after_abatement":{"type":"number","title":"Ftc Iwtc After Abatement","description":"What is left of the pool."},"best_start_before_abatement":{"type":"number","title":"Best Start Before Abatement","description":"Best Start at the full rate."},"best_start_abatement":{"type":"number","title":"Best Start Abatement","description":"21 cents per dollar above $79,000, per income-tested child. The website does not apply this and so overstates it."},"best_start_annual":{"type":"number","title":"Best Start Annual","description":"Best Start after its own abatement."},"total_annual":{"type":"number","title":"Total Annual","description":"Everything, for the year."},"total_weekly":{"type":"number","title":"Total Weekly","description":"The same, a week."},"total_fortnightly":{"type":"number","title":"Total Fortnightly","description":"The same, a fortnight."},"fully_abated":{"type":"boolean","title":"Fully Abated","description":"True when income has wiped out FTC and IWTC entirely."},"tax_year":{"type":"string","title":"Tax Year","description":"Tax year the rates are for."},"assumptions":{"additionalProperties":true,"type":"object","title":"Assumptions","description":"Every rate and threshold used, so a stored result can be audited later."},"differences_from_website":{"items":{"type":"string"},"type":"array","title":"Differences From Website","description":"Where this deliberately does not match the website page, and why. Empty since 29 August 2026, when the page was corrected: it held the abolished In-Work Tax Credit hours test, Best Start paid without its abatement, and Best Start asked for as babies under one rather than children under three."},"excludes":{"items":{"type":"string"},"type":"array","title":"Excludes","description":"What this does not calculate."}},"type":"object","required":["children","children_under_3","family_income","ftc_annual","iwtc_annual","iwtc_eligible","combined_ftc_iwtc_before_abatement","abatement","ftc_iwtc_after_abatement","best_start_before_abatement","best_start_abatement","best_start_annual","total_annual","total_weekly","total_fortnightly","fully_abated","tax_year","assumptions","differences_from_website","excludes"],"title":"WorkingForFamiliesResult"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","description":"Optional. Identifies your calls and raises your hourly limit from 120 to 5000 requests. Request one from contact@calculate.co.nz","in":"header","name":"X-API-Key"}}},"tags":[{"name":"Calculators","description":"New Zealand tax, money and health calculations. Each one is a port of the calculator of the same name on calculate.co.nz, and the website is the reference: where the two disagree the API is wrong until proven otherwise, and the test suite fails the build."},{"name":"Discovery","description":"Find the right page across all 2,377 calculators, 407 guides and 49 datasets. Only a handful of calculators have their own endpoint; everything else is reachable here as a URL."},{"name":"Reference data","description":"Current, dated, sourced New Zealand statutory rates: tax brackets, ACC, student loan, KiwiSaver, benefits. Maintained on a review calendar tied to when each figure actually changes, and consumed by the calculators above, so a wrong rate breaks a page rather than sitting unnoticed in a feed."},{"name":"Service","description":"Liveness and the state of the search index."}]}