Skip to content

Social Security

Benefit estimation, claiming strategies, and SSA limits.


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

Section titled “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 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

Section titled “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 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

Section titled “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 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 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.