Retirement

Savings waterfall — next-dollar ordering of annual savings

Answers "I have $X a year to save — where does each dollar go?" by filling the standard tax-advantaged waterfall in priority order: 401(k) to the full employer match, then HSA, then IRA (annotated with the Roth route — direct / backdoor / traditional), then the rest of the 401(k) elective-deferral limit, then a taxable account. Reports the dollar to each bucket, the employer match captured, and the unused tax-advantaged room. Composes the contribution-limit and IRA-eligibility engines, so the limits stay current automatically. Deterministic; not financial advice.

post/v1/savings-waterfall

Request

  • Base URL: https://api.numeratica.com
  • URL: https://api.numeratica.com/v1/savings-waterfall
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

tax_year2025 | 2026 required
ageinteger required

Drives IRA/401(k)/HSA catch-ups.

filing_status'single' | 'mfj' | 'mfs' | 'hoh' required
maginumber

For the Roth-IRA phase-out (the IRA-step route).

compensationnumber

Salary / earned income (caps the limits + the match).

annual_savingsnumber required

The amount to allocate this year.

hsa_coverage'none' | 'self' | 'family'

HDHP coverage tier (default none).

employer_match_ratenumber

Match rate (e.g. 0.5 = 50 cents/$).

employer_match_cap_pctnumber

Match cap as a share of compensation (e.g. 0.06).

covered_by_workplace_planboolean

Traditional-IRA deduction phase-out annotation (defaults true when a match/deferral is present).

prior_year_wagesnumber

SECURE 2.0 §603 Roth-catch-up flag (2026+).

Response

The ordered allocation plan

result_idstring
engine_versionstring
disclaimerstring

Example response

{
  "result_id": "savingswf_1a2b3c4d5e6f7a8b",
  "engine_version": "savings-waterfall-1.0.0"
}

Changes

No recorded changes to this operation across all 1 revision of this API.