Skip to content

Social Security

Benefit estimation, claiming strategies, and SSA limits.

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
birth_year int required Birth year

Returns a table of monthly and annual benefits for each claiming age,

estimate_social_security_pia_from_salary

Estimate Primary Insurance Amount (PIA) from annual 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)

Returns: annual_salary_cents, annual_salary_dollars, years_of_work, estimated_pia_cents, estimated_pia_dollars, source, notes, 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
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%). When provided and cola_rate is not set, COLA defaults to the inflation rate. Also used to compute total_real_cents (present-value total in today's dollars).

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.

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_spousal_benefit

Estimate spousal Social Security benefit.

Parameter Type Default Description
worker_pia_cents int required Worker's Primary Insurance Amount in cents
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.

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