Skip to content

Personal finance · Calculation

Savings plan milestones and comparisons

Find the first projected year a savings goal is reached, compare interest with annual deposits, and review the displayed schedule, a $100/month alternative and the app’s sensitivity grid.

Example result · projection.finalBalance: 83434.00071898063 See output

Cost per success
2 calculation credits
Production plans
Standard, Business, Scale, Enterprise
Plan allowances
Free sandbox
Not available

Integration example

Make a request

Use a production key scoped to savings-plan-milestones.

Keep the key on your server. A successful call uses 2 calculation credits.

Production request

Set HT_PRODUCTION_KEY on your server. Save as example.mjs and run node example.mjs with Node.js 18 or later.

import { randomUUID } from "node:crypto";

const key = process.env.HT_PRODUCTION_KEY;
if (!key) throw new Error("Set HT_PRODUCTION_KEY on your server.");
const endpoint = "https://calc.hasstechapi.com/v2/calc/savings-plan-milestones";
const input = {
  "initialDeposit": 5000,
  "monthlyContribution": 500,
  "annualRate": 4.5,
  "years": 10,
  "compounding": "monthly",
  "goal": 75000
};
const requestId = process.env.HT_REQUEST_ID || Date.now() + "." + randomUUID();
// Keep this ID to look up usage if the connection is interrupted.
console.error("Usage lookup ID:", requestId);

const response = await fetch(endpoint, {
  method: "POST",
  redirect: "error",
  headers: {
    "Authorization": "Bearer " + key,
    "Content-Type": "application/json",
    "Idempotency-Key": requestId
  },
  body: JSON.stringify(input)
});
if (!response.ok) {
  const problem = await response.json().catch(() => null);
  const code = problem?.error?.code || response.statusText;
  const delay = response.headers.get("retry-after");
  if (delay) console.error("Retry-After (seconds):", delay);
  console.error("HTTP " + response.status + " " + code + ". Usage lookup ID: " + requestId);
  if (Array.isArray(problem?.error?.details)) {
    for (const issue of problem.error.details) console.error("Input issue:", JSON.stringify(issue));
  }
  process.exitCode = 1;
} else {
  console.log(JSON.stringify(await response.json(), null, 2));
}
cURL (shell)

Set HT_PRODUCTION_KEY on your server. Run in a POSIX shell with cURL 7.76+ and Python 3.7+ to create a request ID.

(
  set -eu
  : "${HT_PRODUCTION_KEY:?Set HT_PRODUCTION_KEY on your server}"
  request_id="${HT_REQUEST_ID:-}"
  if [ -z "$request_id" ]; then
    request_id=$(python3 -c 'import time, uuid; print(str(time.time_ns() // 1000000) + "." + str(uuid.uuid4()))')
  fi
  printf 'Usage lookup ID: %s\n' "$request_id" >&2
  # On INVALID_INPUT, read error.details in the JSON response body.
  curl --disable --silent --show-error --fail-with-body --include \
    --request POST 'https://calc.hasstechapi.com/v2/calc/savings-plan-milestones' \
    --header "Authorization: Bearer $HT_PRODUCTION_KEY" \
    --header 'Content-Type: application/json' \
    --header "Idempotency-Key: $request_id" \
    --data-binary @- <<'HT_INPUT'
{
  "initialDeposit": 5000,
  "monthlyContribution": 500,
  "annualRate": 4.5,
  "years": 10,
  "compounding": "monthly",
  "goal": 75000
}
HT_INPUT
)
If your request fails
400 INVALID_INPUT

Read error.details when present. Node prints each issue. cURL returns the JSON body. Each path points into your request. An empty path refers to the whole body.

Check the accepted inputs for required fields, units and ranges. Send the corrected JSON as a new request.

401 or 403
Check that the server has the bearer key for the endpoint’s environment and that the key includes savings-plan-milestones.
429
Read the service error code, check your allowance, and wait for the Retry-After interval when supplied before trying again.
Lost response, 409 or 503
Open Request lookup, select the same environment and enter the printed usage lookup ID. A settled ID has already consumed credits. To retry the same calculation, set HT_REQUEST_ID to the original ID and reuse the same inputs. A settled request does not return its result again. Unset the variable for a new request, which can consume credits.

The usage lookup ID is the Idempotency-Key your server sends. The response’s x-request-id identifies the HTTP exchange for support.

Output

Example result

These values come from running this operation on the example inputs.

projection.finalBalance
83434.00071898063
projection.totalContributions
65000
projection.totalInterest
18434.000718980635
How to interpret this result
  • Constant nominal rate and contributions, with no withdrawals, fees, taxes or inflation adjustment.
  • Monthly mode credits interest then adds the monthly deposit. Daily mode credits interest daily then adds one 365th of the annual contribution.
  • Milestones use rounded year-end balances, including year one if the opening deposit already covers the goal. Crossover uses the year’s displayed interest and requires positive annual deposits.
  • Whole-dollar interest subtracts displayed contributions from displayed balance. A sensitivity cell outside the 15% rate cap is null; its formatted cell is an em dash.
Full example response (JSON)
{
  "status": "available",
  "result": {
    "projection": {
      "finalBalance": 83434.00071898063,
      "totalContributions": 65000,
      "totalInterest": 18434.000718980635
    },
    "shown": {
      "balance": 83434,
      "contributions": 65000,
      "interest": 18434
    },
    "interestSharePercent": 22.09411098608272,
    "shownInterestSharePercent": 22,
    "schedule": [
      {
        "year": 1,
        "balance": 11355,
        "contributions": 11000,
        "interest": 355,
        "yearInterest": 355,
        "depositEquivalentMonths": 0
      },
      {
        "year": 2,
        "balance": 18002,
        "contributions": 17000,
        "interest": 1002,
        "yearInterest": 647,
        "depositEquivalentMonths": 1
      },
      {
        "year": 3,
        "balance": 24954,
        "contributions": 23000,
        "interest": 1954,
        "yearInterest": 952,
        "depositEquivalentMonths": 1
      },
      {
        "year": 4,
        "balance": 32226,
        "contributions": 29000,
        "interest": 3226,
        "yearInterest": 1272,
        "depositEquivalentMonths": 2
      },
      {
        "year": 5,
        "balance": 39832,
        "contributions": 35000,
        "interest": 4832,
        "yearInterest": 1606,
        "depositEquivalentMonths": 3
      },
      {
        "year": 6,
        "balance": 47787,
        "contributions": 41000,
        "interest": 6787,
        "yearInterest": 1955,
        "depositEquivalentMonths": 3
      },
      {
        "year": 7,
        "balance": 56108,
        "contributions": 47000,
        "interest": 9108,
        "yearInterest": 2321,
        "depositEquivalentMonths": 4
      },
      {
        "year": 8,
        "balance": 64810,
        "contributions": 53000,
        "interest": 11810,
        "yearInterest": 2702,
        "depositEquivalentMonths": 5
      },
      {
        "year": 9,
        "balance": 73913,
        "contributions": 59000,
        "interest": 14913,
        "yearInterest": 3103,
        "depositEquivalentMonths": 6
      },
      {
        "year": 10,
        "balance": 83434,
        "contributions": 65000,
        "interest": 18434,
        "yearInterest": 3521,
        "depositEquivalentMonths": 7
      }
    ],
    "milestoneYears": [
      1,
      5,
      10
    ],
    "crossoverYear": null,
    "goal": {
      "amount": 75000,
      "reachedYear": 10,
      "endingShortfall": 0
    },
    "hundredMore": {
      "monthlyContribution": 600,
      "finalBalance": 98553.80808649494,
      "extraContributions": 12000,
      "shownBalanceGain": 15120
    },
    "explanation": {
      "toolId": "savings",
      "headline": "Starting with $5,000 and adding $500 a month at 4.5%, you would have $83,434 after 10 years: $65,000 you put in and $18,434 of interest.",
      "math": [
        {
          "label": "What you put in",
          "formula": "first deposit + monthly deposit × 12 × years",
          "substituted": "$5,000 + $500 × 12 × 10",
          "result": "$65,000"
        },
        {
          "label": "How the balance grows",
          "formula": "each month: balance × (1 + rate ÷ 12) + the monthly deposit",
          "substituted": "4.5% a year, compounded monthly, for 10 years",
          "result": "$83,434"
        },
        {
          "label": "Interest earned",
          "formula": "final balance − what you put in",
          "substituted": "$83,434 − $65,000",
          "result": "$18,434"
        }
      ],
      "drivers": [
        {
          "label": "A rate 1 percentage point higher",
          "detail": "+$4,975 after 10 years",
          "delta": 4975,
          "favorable": true
        },
        {
          "label": "$100 more a month",
          "detail": "+$15,120 after 10 years",
          "delta": 15120,
          "favorable": true
        },
        {
          "label": "Saving 5 years longer",
          "detail": "+$54,581 by year 15",
          "delta": 54581,
          "favorable": true
        }
      ],
      "metrics": [
        {
          "label": "Future balance",
          "value": "$83,434",
          "hint": "after 10 years"
        },
        {
          "label": "You put in",
          "value": "$65,000"
        },
        {
          "label": "Interest earned",
          "value": "$18,434",
          "hint": "22% of the balance"
        }
      ],
      "splitsHeading": "Over the whole plan",
      "splits": [
        {
          "title": "Your balance after 10 years",
          "total": "$83,434",
          "parts": [
            {
              "label": "You put in",
              "value": 65000,
              "display": "$65,000"
            },
            {
              "label": "Interest",
              "value": 18434.000718980635,
              "display": "$18,434"
            }
          ]
        }
      ],
      "alternative": {
        "label": "$100 more a month",
        "current": [
          {
            "label": "Monthly deposit",
            "value": "$500"
          },
          {
            "label": "Balance after 10 years",
            "value": "$83,434"
          },
          {
            "label": "Interest earned",
            "value": "$18,434"
          }
        ],
        "alternative": [
          {
            "label": "Monthly deposit",
            "value": "$600"
          },
          {
            "label": "Balance after 10 years",
            "value": "$98,554"
          },
          {
            "label": "Interest earned",
            "value": "$21,554"
          }
        ],
        "takeaway": "Adding $100 a month puts $12,000 more in and grows the balance by $15,120."
      },
      "deepDive": {
        "sensitivity": {
          "metric": "Balance after 10 years",
          "rowAxis": "Rate",
          "columnAxis": "Monthly deposit",
          "columns": [
            "-$100/mo",
            "Yours",
            "+$100/mo"
          ],
          "baseColumn": 1,
          "rows": [
            {
              "label": "4%",
              "cells": [
                "$66,354",
                "$81,079",
                "$95,804"
              ],
              "values": [
                66354.08530228135,
                81079.0657748289,
                95804.0462473764
              ],
              "isBase": false
            },
            {
              "label": "4.25%",
              "cells": [
                "$67,325",
                "$82,246",
                "$97,167"
              ],
              "values": [
                67325.11663569833,
                82245.84281282318,
                97166.5689899479
              ],
              "isBase": false
            },
            {
              "label": "4.5% (yours)",
              "cells": [
                "$68,314",
                "$83,434",
                "$98,554"
              ],
              "values": [
                68314.19335146624,
                83434.00071898063,
                98553.80808649494
              ],
              "isBase": true
            },
            {
              "label": "4.75%",
              "cells": [
                "$69,322",
                "$84,644",
                "$99,966"
              ],
              "values": [
                69321.68258122665,
                84643.96925069996,
                99966.25592017338
              ],
              "isBase": false
            },
            {
              "label": "5%",
              "cells": [
                "$70,348",
                "$85,876",
                "$101,404"
              ],
              "values": [
                70347.95926671855,
                85876.18721128529,
                101404.415155852
              ],
              "isBase": false
            }
          ]
        },
        "risks": [],
        "balances": [
          {
            "label": "After 1 year",
            "value": "$11,355"
          },
          {
            "label": "After 5 years",
            "value": "$39,832"
          },
          {
            "label": "After 10 years",
            "value": "$83,434"
          }
        ]
      },
      "note": "Assumes the same rate and deposits every year, with nothing taken out; taxes and fees are not included."
    }
  },
  "formulaVersion": "savings-plan-milestones-1.0.0",
  "units": {
    "projection, shown, schedule amount fields, goal amounts, hundredMore dollar fields": "USD",
    "interestSharePercent, shownInterestSharePercent, annualRate": "percentage points",
    "schedule.year, milestoneYears, crossoverYear, reachedYear": "end of projection year",
    "depositEquivalentMonths": "whole monthly deposits",
    "hundredMore.monthlyContribution": "USD/month"
  },
  "assumptions": [
    "Constant nominal rate and contributions, with no withdrawals, fees, taxes or inflation adjustment.",
    "Monthly mode credits interest then adds the monthly deposit. Daily mode credits interest daily then adds one 365th of the annual contribution.",
    "Milestones use rounded year-end balances, including year one if the opening deposit already covers the goal. Crossover uses the year’s displayed interest and requires positive annual deposits.",
    "Whole-dollar interest subtracts displayed contributions from displayed balance. A sensitivity cell outside the 15% rate cap is null; its formatted cell is an em dash."
  ],
  "warnings": [],
  "creditCost": 2
}

Request contract

Accepted inputs

Fields for this example. Expand the schema for all supported combinations and limits.

FieldType, units and limits

initialDepositRequired
number

Opening deposit in USD.

Min 0 · Max 100000000 · Step 0.01
monthlyContributionRequired
number

Contribution in USD per month. Daily mode distributes this across 365 periods per year.

Min 0 · Max 10000000 · Step 0.01
annualRateRequired
number

Fixed annual nominal rate in percentage points (4.5 means 4.5%).

Min 0 · Max 15
yearsRequired
integer

Whole projection years.

Min 1 · Max 100
compoundingRequired
string

Contribution and crediting cadence; interest accrues before each period-end deposit.

Allowed: "monthly", "daily"
goalOptional
number

Optional USD goal. Manual goals use whole dollars. Share links can supply a goal with cents up to $100 million. Zero or omission disables the goal.

Min 0 · Max 9007199254740991
Example request body (JSON)
{
  "initialDeposit": 5000,
  "monthlyContribution": 500,
  "annualRate": 4.5,
  "years": 10,
  "compounding": "monthly",
  "goal": 75000
}
Full JSON schema
{
  "type": "object",
  "properties": {
    "initialDeposit": {
      "type": "number",
      "minimum": 0,
      "maximum": 100000000,
      "description": "Opening deposit in USD.",
      "multipleOf": 0.01
    },
    "monthlyContribution": {
      "type": "number",
      "minimum": 0,
      "maximum": 10000000,
      "description": "Contribution in USD per month. Daily mode distributes this across 365 periods per year.",
      "multipleOf": 0.01
    },
    "annualRate": {
      "type": "number",
      "minimum": 0,
      "maximum": 15,
      "description": "Fixed annual nominal rate in percentage points (4.5 means 4.5%)."
    },
    "years": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Whole projection years."
    },
    "compounding": {
      "type": "string",
      "enum": [
        "monthly",
        "daily"
      ],
      "description": "Contribution and crediting cadence; interest accrues before each period-end deposit."
    },
    "goal": {
      "type": "number",
      "minimum": 0,
      "maximum": 9007199254740991,
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "number",
          "minimum": 0,
          "maximum": 100000000,
          "description": "Shared savings goal in USD.",
          "multipleOf": 0.01
        }
      ],
      "description": "Optional USD goal. Manual goals use whole dollars. Share links can supply a goal with cents up to $100 million. Zero or omission disables the goal."
    }
  },
  "required": [
    "initialDeposit",
    "monthlyContribution",
    "annualRate",
    "years",
    "compounding"
  ],
  "additionalProperties": false
}

Production endpoint: POST https://calc.hasstechapi.com/v2/calc/savings-plan-milestones
Formula: savings-plan-milestones-1.0.0

Related PDF reports