The benefit object

Represents benefits available to employees.

Use the benefit object to capture benefit types, start and end dates, and employee and company contributions. Benefits will be taken into consideration when calculating a particular employee's net pay.

{
  "id": "ben_lrcYUhTk1FVZl2vSCOBP",
  "employee": "emp_kKTK4VafMNc5pIbI0G9x",
  "benefit": "401k",
  "company_benefit": null,
  "source": null,
  "external": false,
  "period": null,
  "description": "Guideline 401(k)",
  "effective_start": "2020-01-01",
  "effective_end": null,
  "company_contribution_amount": null,
  "company_contribution_percent": 1.0,
  "company_period_amount": null,
  "employee_contribution_amount": null,
  "employee_contribution_percent": 1.0,
  "employee_period_amount": null,
  "hsa_contribution_limit": null,
  "metadata": {}
}
AttributeDescription
id
string
Unique identifier for the employee benefit.
employee
string
ID of the employee that this employee benefit relates to.
benefit
string
The benefit type. See types of benefits for a complete list of supported benefit types.
company_benefit
string
(Optional) The company benefit associated with this employee benefit.
source
string
Read-only field that indicates the source that created the object. Will be null unless you expect a third-party to be managing objects in your system.
period
string
The period over which a period amount is distributed. Can be “monthly” or null. See the Period Benefits guide for more information.
description
string
Human-readable name identifying the employee benefit.
effective_start
YYYY-MM-DD
The date this benefit should be considered effective. Payrolls with a payday before this date will not include the benefit.
effective_end
YYYY-MM-DD
The date this benefit should be no longer be considered effective. Payrolls with a payday after this date will not include the benefit.
company_contribution_amount
string
How much the company should contribute toward this employee benefit every payroll, expressed as a dollar amount.
company_contribution_percent
float
How much the company should contribute toward this employee benefit every payroll, expressed as a percentage of employee earnings.
company_period_amount
string
How much the company should contribute towards this employee benefit across a period, expressed as a dollar amount. See the Period Benefits guide for more information.
employee_contribution_amount
string
How much the employee should contribute from their paycheck toward this employee benefit every payroll, expressed as a dollar amount.
employee_contribution_percent
float
How much the employee should contribute from their paycheck toward this employee benefit every payroll, expressed as a percentage of employee earnings.
employee_period_amount
string
How much the employee should contribute towards this employee benefit across a period, expressed as a dollar amount. See the Period Benefits guide for more information.
hsa_contribution_limit
string
The contribution limit for a HSA benefit. Only applicable for benefits of type hsa and must be either single or family. If not provided, defaults to single.
external
boolean
Read-only flag that indicates if this benefit was created automatically upon importing an external payroll, most commonly during the historical payroll import process.

External benefits cannot be edited.
metadata
object
Additional loosely structured information to associate with this employee benefit.