Skip to content

Employer Match

Match formulas, vesting, and calculations.

create_employer_match

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, 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.
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
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: formula_type, tiers, non_elective_pct, discretionary_pct, vesting_schedule, annual_match_cap_cents, is_qaca, and true_up.

calculate_401k_employer_match

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

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_401k_vested_amount

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.