---
title: "Savings waterfall — next-dollar ordering of annual savings"
method: POST
path: "/v1/savings-waterfall"
tags: ["Retirement"]
---

# Savings waterfall — next-dollar ordering of annual savings

`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`

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.

## Request body

- SavingsWaterfallRequest
  - `tax_year` 2025 | 2026, required
  - `age` integer, required: Drives IRA/401(k)/HSA catch-ups.
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
  - `magi` number: For the Roth-IRA phase-out (the IRA-step route).
  - `compensation` number: Salary / earned income (caps the limits + the match).
  - `annual_savings` number, required: The amount to allocate this year.
  - `hsa_coverage` 'none' | 'self' | 'family': HDHP coverage tier (default none).
  - `employer_match_rate` number: Match rate (e.g. 0.5 = 50 cents/$).
  - `employer_match_cap_pct` number: Match cap as a share of compensation (e.g. 0.06).
  - `covered_by_workplace_plan` boolean: Traditional-IRA deduction phase-out annotation (defaults true when a match/deferral is present).
  - `prior_year_wages` number: SECURE 2.0 §603 Roth-catch-up flag (2026+).

## Response `200`

The ordered allocation plan

- SavingsWaterfallResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` SavingsWaterfallRequest
    - `tax_year` 2025 | 2026, required
    - `age` integer, required: Drives IRA/401(k)/HSA catch-ups.
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
    - `magi` number: For the Roth-IRA phase-out (the IRA-step route).
    - `compensation` number: Salary / earned income (caps the limits + the match).
    - `annual_savings` number, required: The amount to allocate this year.
    - `hsa_coverage` 'none' | 'self' | 'family': HDHP coverage tier (default none).
    - `employer_match_rate` number: Match rate (e.g. 0.5 = 50 cents/$).
    - `employer_match_cap_pct` number: Match cap as a share of compensation (e.g. 0.06).
    - `covered_by_workplace_plan` boolean: Traditional-IRA deduction phase-out annotation (defaults true when a match/deferral is present).
    - `prior_year_wages` number: SECURE 2.0 §603 Roth-catch-up flag (2026+).
  - `result` object
    - `steps` object[]
      - `order` integer
      - `account` '401k_match' | 'hsa' | 'ira' | '401k_remainder' | 'taxable'
      - `amount` number
      - `limit` number: The account's annual limit (0 = uncapped).
      - `cumulative` number: Total allocated through this step.
      - `rationale` string
      - `note` string: e.g. the Roth route on the IRA step.
    - `total_allocated` number
    - `tax_advantaged_allocated` number
    - `taxable_allocated` number
    - `employer_match_captured` number: The free money secured (prorated if under-funded).
    - `full_match_captured` boolean
    - `unused_tax_advantaged_room` number: Headroom left if more were saved.
    - `roth_route` 'roth_direct' | 'roth_partial' | 'backdoor' | 'traditional'
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)