Skip to content

Employer Match

Match formulas, vesting, and calculations.


Create an employer matching configuration for a 401(k) plan.

Parameter Type Default Description
formula_type string required Type of matching formula. Options: basic_safe_harbor, qaca_safe_harbor, enhanced_safe_harbor, non_elective, tiered, or discretionary
tiers list null Match tiers for tiered/enhanced formulas. List of {match_rate, up_to_deferral_pct} objects. Note the units: match_rate is a 0-1 decimal (0.5 = 50% match), while up_to_deferral_pct is a 0-100 percentage — as are non_elective_pct and discretionary_pct. (match_rate is the one rate expressed as a fraction.)
non_elective_pct float null Contribution % for non-elective formula (min 3% for safe harbor)
discretionary_pct float null Current discretionary match percentage
vesting_type string null Vesting schedule type (defaults based on formula). Options: immediate, cliff, or graded
cliff_years int null Cliff years (for cliff vesting)
graded_schedule dict[str, int] null Graded schedule as {years: pct}
annual_match_cap_cents int null Optional annual cap on employer match in cents
is_qaca bool false Qualified Automatic Contribution Arrangement (allows 2-yr cliff)
true_up bool false Whether employer provides year-end true-up

Returns: employer_match, is_safe_harbor, and max_match_pct.


Calculate the employer match for a given employee contribution.

Parameter Type Default Description
employer_match_json object required Employer match configuration as JSON (from create_employer_match)
employee_contribution_cents int required Employee deferral amount in cents
annual_compensation_cents int required Annual compensation in cents
ytd_employer_match_cents int 0 Year-to-date employer match already contributed
include_monthly bool false If True, also calculate monthly match by dividing annual by 12
include_max_match bool false If True, also calculate maximum possible annual employer match
compensation_limit_cents int null IRS annual compensation limit for the projection year, in cents. Defaults to the 2026 limit when omitted.

Returns: employer_match_cents, employer_match_dollars, employee_contribution_cents, employee_contribution_dollars, eligible_compensation_cents, eligible_compensation_dollars, effective_deferral_pct, effective_match_pct, was_compensation_capped, and was_match_capped, and more.


Calculate the vested portion of employer contributions.

Parameter Type Default Description
employer_match_json object required Employer match configuration as JSON
total_employer_contributions_cents int required Total employer contributions in cents
years_of_service int required Years of service with employer

Returns: vested_amount_cents, vested_amount_dollars, unvested_amount_cents, unvested_amount_dollars, vested_percentage, years_of_service, total_employer_contributions_cents, total_employer_contributions_dollars, vesting_type, and summary.


Plan the per-paycheck 401(k) deferral that reaches the year’s limit.

Parameter Type Default Description
tax_year int required Tax year, 2024 or later
ytd_deferral_cents int required Elective deferrals already made this year, in cents, from the latest paystub. Include deferrals to every 401(k)-family plan the person has this year, since the limit is shared across them.
remaining_pay_periods int required Paychecks left in the year, including the next one
per_period_gross_cents int required Gross pay on each remaining paycheck, in cents
employer_match_json object null Optional employer match configuration (from create_employer_match, or an account’s employer_match). Gives the match captured and, through its true_up flag, whether stopping deferrals early forfeits match.
birth_year int null Optional birth year; sets the catch-up by the age attained in tax_year.
age int null Optional age attained by December 31 of tax_year. Overrides birth_year. Omit both for the limit without catch-up.
election_type string "flat" Whether to recommend a flat dollar election or a percentage of pay.
proposed_election_cents int null Optional flat per-paycheck election to evaluate, in cents.
proposed_election_pct float null Optional percentage-of-pay election to evaluate (0-100).
account_type string "traditional_401k" The 401(k) account type; both share one deferral limit.. Options: traditional_401k or roth_401k

Returns: tax_year, account_type, limit, ytd_deferral_cents, remaining_limit_cents, remaining_pay_periods, per_period_gross_cents, recommended, proposed, and employer_match, and more.