{
  "openapi": "3.1.0",
  "info": {
    "title": "HECS-HELP Repayment API",
    "version": "1.0.0",
    "summary": "Compulsory Australian study and training support loan repayments.",
    "description": "Calculates the compulsory annual repayment on an Australian HECS-HELP or other study and training support loan, from the ATO's published thresholds and marginal rates.\n\nNo API key, no registration and no rate limit. General information only, not financial or tax advice. Not affiliated with, and not endorsed by, the Australian Taxation Office or the Commonwealth of Australia.\n\nFigures last verified against ato.gov.au on 21 September 2026.",
    "license": {
      "name": "Free to use, attribution appreciated"
    },
    "contact": {
      "url": "https://hecscalculator.com/developers/"
    }
  },
  "servers": [
    {
      "url": "https://hecscalculator.com"
    }
  ],
  "paths": {
    "/api/v1/repayment": {
      "get": {
        "operationId": "calculateRepayment",
        "summary": "Calculate a compulsory HECS-HELP repayment",
        "parameters": [
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "description": "Repayment income for the period given by `frequency`. Repayment income is broader than taxable income."
          },
          {
            "name": "frequency",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "week",
                "fortnight",
                "month",
                "year"
              ],
              "default": "year"
            }
          },
          {
            "name": "financial_year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "2025-26",
                "2026-27"
              ],
              "default": "2026-27"
            }
          },
          {
            "name": "reportable_fringe_benefits",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "description": "Annual add-back. Not scaled by `frequency`."
          },
          {
            "name": "net_investment_loss",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "description": "Annual add-back. Not scaled by `frequency`."
          },
          {
            "name": "reportable_super_contributions",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "description": "Annual add-back. Not scaled by `frequency`."
          },
          {
            "name": "exempt_foreign_income",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "description": "Annual add-back. Not scaled by `frequency`."
          }
        ],
        "responses": {
          "200": {
            "description": "The compulsory repayment and its breakdown.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid parameter.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "calculateRepaymentJson",
        "summary": "Calculate a compulsory HECS-HELP repayment (JSON body)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "As above."
          }
        }
      }
    },
    "/api/v1/rates": {
      "get": {
        "operationId": "getRates",
        "summary": "ATO thresholds, marginal rates and indexation history",
        "parameters": [
          {
            "name": "financial_year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "2025-26",
                "2026-27"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The rate table with provenance."
          }
        }
      }
    }
  }
}