Skip to content

Social Security

Benefit estimation, claiming strategies, and SSA limits.

estimate_social_security_breakeven_age

Estimate the breakeven age for Social Security claiming strategies.

Parameter Type Default Description
pia_cents int required Primary Insurance Amount in cents; must be greater than 0. A PIA of 0 means the worker has fewer than 40 credits and is not insured, so no breakeven age exists for it.
birth_year int required Birth year
early_claiming_age_years int 62 Early claiming age in years
early_claiming_age_months int 0 Early claiming age additional months
later_claiming_age_years int null Later claiming age in years (defaults to FRA)
later_claiming_age_months int 0 Later claiming age additional months

Returns: pia_cents, pia_dollars, birth_year, full_retirement_age, breakeven_age_years, breakeven_age_display, and summary.

apply_social_security_earnings_test

Apply the Social Security earnings test.

Parameter Type Default Description
annual_benefit_cents int required Annual Social Security benefit in cents
annual_earnings_cents int required Annual earnings from work in cents
claiming_age_years int required Claiming age in years
birth_year int required Birth year
claiming_age_months int 0 Additional months (0-11)
is_fra_year bool false Whether this is the FRA year
year int null Tax year (optional, for limit lookup)

Returns: annual_benefit_before_cents, annual_benefit_before_dollars, annual_earnings_cents, annual_earnings_dollars, birth_year, earnings_limit_cents, earnings_limit_dollars, adjusted_annual_benefit_cents, adjusted_annual_benefit_dollars, and benefit_reduction_cents, and more.

get_social_security_earnings_limit

Get the Social Security earnings limit.

Parameter Type Default Description
claiming_age_years int required Claiming age in years
birth_year int required Birth year
claiming_age_months int 0 Additional months (0-11)
is_fra_year bool false Whether this is the FRA year
year int null Tax year (optional, for limit lookup)

Returns: birth_year, earnings_limit_cents, earnings_limit_dollars, monthly_limit_cents, monthly_limit_dollars, and summary.

estimate_social_security_benefits_all_ages

Estimate Social Security benefits at all possible claiming ages (62-70).

Parameter Type Default Description
pia_cents int required Primary Insurance Amount in cents; must be greater than 0. A PIA of 0 means the worker has fewer than 40 credits and is not insured, so no claiming-age benefit table exists for it.
birth_year int required Birth year

Returns a table of monthly and annual benefits for each claiming age, making it easy to compare the impact of different claiming strategies.

estimate_social_security_pia_from_salary

Estimate Primary Insurance Amount (PIA) from one flat career salary.

Parameter Type Default Description
annual_salary_cents int required Annual salary in cents (e.g., 10000000 = $100,000)
years_of_work int required Number of years working at this salary (1-45). Fewer than 35 years zero-fills the remainder, lowering the estimated PIA.
year int null (see source)

Returns: annual_salary_cents, annual_salary_dollars, years_of_work, year, estimated_pia_cents, estimated_pia_dollars, source, notes, and summary.

estimate_social_security_pia_from_earnings_record

Estimate Primary Insurance Amount (PIA) from a year-by-year earnings record.

Parameter Type Default Description
earnings_by_year dict[int, int] required Social Security taxable earnings by calendar year, in cents (e.g. {"2023": 8500000} = $85,000 in 2023). Use the Social Security taxable earnings column of an SSA statement, NOT the Medicare wages column: Medicare wages are uncapped, and any year above that year's taxable maximum is rejected.
date_of_birth string required Date of birth as an ISO date (YYYY-MM-DD), not a birth year. SSA deems a person to attain an age the day BEFORE their birthday, so a January 1 birth attains 60 and 62 in the preceding calendar year, which shifts the eligibility year and the indexing year.
stop_work_year int required Last calendar year the worker works, INCLUSIVE, at the full future_annual_earnings_cents amount. 'Stop work at 63' means the year the worker turns 63 is worked in full. A partial final year is expressed by supplying that year's earnings directly in earnings_by_year instead.
future_annual_earnings_cents int required Earnings for each year after the last recorded one through stop_work_year, in cents, in TODAY'S dollars — do not inflate them.

Returns: pia_cents_today_dollars, pia_dollars_today_dollars, is_retirement_insured, credits_earned, aime_cents, aime_dollars, top_35_years, indexed_earnings_by_year, if_worked_to_fra, and eligibility_year, and more.

calculate_social_security_pia_from_aime

Calculate Primary Insurance Amount (PIA) from Average Indexed Monthly Earnings (AIME).

Parameter Type Default Description
aime_cents int required Average Indexed Monthly Earnings in cents (e.g. 500000 = $5,000/month). AIME is the average of a worker's 35 highest wage-indexed earning years over 420 months; an SSA statement reports it, and estimate_social_security_pia_from_earnings_record computes it from a year-by-year earnings record. Do NOT pass an annual salary here.
year int required (see source)

Returns: pia_cents, pia_dollars, aime_cents, aime_dollars, year, bend_points, and summary.

calculate_social_security_lifetime_benefits

Calculate total lifetime Social Security benefits.

Parameter Type Default Description
pia_cents int required Primary Insurance Amount in cents; must be greater than 0. A PIA of 0 means the worker has fewer than 40 credits and is not insured, so no lifetime benefit table exists for it.
claiming_age_years int required Claiming age in years (62-70)
life_expectancy_years int required Expected age at death
birth_year int required Birth year
claiming_age_months int 0 Additional months (0-11)
inflation float 0.0 Annual inflation rate as decimal (e.g., 0.03 = 3%). Defaults to 0.0 (no inflation, 0% COLA). When cola_rate is not set, COLA defaults to this inflation rate. Also used to compute total_real_cents (present-value total in today's dollars).
cola_rate float null Annual Social Security COLA rate as decimal (e.g., 0.025 = 2.5%). Overrides the inflation-derived COLA when set, letting benefits grow at a different rate than the inflation used for discounting. When omitted, COLA defaults to the inflation rate.

Returns: pia_cents, pia_dollars, claiming_age, life_expectancy_years, years_collecting, monthly_benefit_cents, monthly_benefit_dollars, lifetime_benefits_nominal_cents, lifetime_benefits_nominal_dollars, and lifetime_benefits_real_cents, and more.

estimate_social_security_spousal_benefit

Estimate spousal Social Security benefit.

Parameter Type Default Description
worker_pia_cents int required Worker's Primary Insurance Amount in cents; must be greater than 0. A PIA of 0 means the worker has fewer than 40 credits and is not insured, so no spousal benefit exists for it.
claiming_age_years int required Spouse's claiming age in years
birth_year int required Spouse's birth year
own_pia_cents int 0 Spouse's own PIA in cents (0 if no own benefit)
claiming_age_months int 0 Additional months (0-11)

Returns: worker_pia_cents, worker_pia_dollars, max_spousal_benefit_at_fra_cents, max_spousal_benefit_at_fra_dollars, claiming_age, monthly_spousal_benefit_cents, monthly_spousal_benefit_dollars, annual_spousal_benefit_cents, annual_spousal_benefit_dollars, and benefit_type, and more.

estimate_social_security_survivor_benefit

Estimate survivor Social Security benefit.

Parameter Type Default Description
deceased_benefit_cents int required Deceased worker's benefit amount in cents
claiming_age_years int required Survivor's claiming age in years (60-70)
birth_year int required Survivor's birth year
own_pia_cents int 0 Survivor's own PIA in cents (0 if no own benefit)
claiming_age_months int 0 Additional months (0-11)

Returns: deceased_benefit_cents, deceased_benefit_dollars, max_survivor_benefit_at_fra_cents, max_survivor_benefit_at_fra_dollars, survivor_claiming_age, monthly_survivor_benefit_cents, monthly_survivor_benefit_dollars, annual_survivor_benefit_cents, annual_survivor_benefit_dollars, and benefit_type, and more.