IRD WFF Rates NZ

Goal

Expose source-backed Inland Revenue (IRD) public parameters for Working for Families tax credits, Best Start, Minimum Family Tax Credit, and FamilyBoost in a small Python CLI.

Use this when

• You need the Family Tax Credit, In-Work Tax Credit, Best Start, or Minimum Family Tax Credit amount table for a tax year.
• You need Working for Families abatement thresholds/rates for entitlement pre-check variables.
• You need FamilyBoost reimbursement rates, quarterly income caps, maximum payments, abatement, or eligibility bullets.
• You need official IRD source URLs for rates and eligibility pages.

Do not use this for

• Calculating a final entitlement or giving tax advice. Direct users to IRD/myIR or the official calculators for decisions.
• Applying for Working for Families or FamilyBoost, logging into myIR, or changing taxpayer details.
• Aggregate WFF statistics, recipient counts, or expenditure datasets; use data-govt-nz for CKAN/data.govt.nz statistics.
• Circumventing bot protection. If IRD source probing is unavailable, treat it as upstream_unavailable and use the cited URL for manual verification.

CLI

python3 skills/ird-wff-rates-nz/scripts/cli.py rates --year 2027 --json
python3 skills/ird-wff-rates-nz/scripts/cli.py thresholds --year 2027 --json
python3 skills/ird-wff-rates-nz/scripts/cli.py credit get family-tax-credit --year 2027 --json
python3 skills/ird-wff-rates-nz/scripts/cli.py credit get best-start --year 2027 --probe --json
python3 skills/ird-wff-rates-nz/scripts/cli.py familyboost --json

Commands:

• rates --year YYYY [--probe] [--json] - all built-in WFF credit amount tables and abatement parameters for a tax year ending 31 March.
• thresholds --year YYYY [--probe] [--json] - WFF and Best Start income thresholds and abatement rates.
• credit get <family-tax-credit|in-work|best-start|mftc> --year YYYY [--probe] [--json] - one credit's amounts, eligibility summary, thresholds, and source URL.
• familyboost [--probe] [--json] - FamilyBoost quarterly reimbursement rates, income caps, maximums, abatement rates, claim quarters, and eligibility bullets.

--probe performs a timed read-only HTTP check against the cited public IRD page and returns availability plus a last-updated snippet when visible. Core JSON remains available without network access.

Operational notes

• Tax year means the year ending 31 March; for example 2027 covers 1 April 2026 to 31 March 2027.
• The helper is standard-library Python only and has no API key, login, cache, browser, or third-party dependency.
• Built-in numeric schedules are intentionally narrow and source-cited; re-check after each Budget/1 April update.

Resources

• CLI: scripts/cli.py
• Smoke test: scripts/smoke_test.py
• Source notes: references/api-notes.md