Employer Match
Match formulas, vesting, and calculations.
create_employer_match
Section titled “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, 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_401k_employer_match
Section titled “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 |
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_401k_vested_amount
Section titled “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.
plan_401k_deferral
Section titled “plan_401k_deferral”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.