---
title: "Update an employee benefit"
method: PUT
path: "/v1/employee_benefits/{employee_benefit_id}"
tags: ["Employee Benefits"]
---

# Update an employee benefit

`PUT /v1/employee_benefits/{employee_benefit_id}`

Employee benefits represent an employee enrolled in a particular company benefit. It includes information specific to that employee's enrollment.

When the application has the `employee_benefits:write:benefit_type_limited` data scope, the application can only update employee benefits for benefit types that are permitted for the application.

scope: `employee_benefits:write`

## Path parameters

- `employee_benefit_id` string, required

## Headers

- `X-Gusto-API-Version` '2026-06-15'

## Request body

- EmployeeBenefitUpdateRequest
  - `version` string, required — The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer) for information on how to use this field.
  - `active` boolean — Whether the employee benefit is active.
  - `employee_deduction` string — The amount to be deducted, per pay period, from the employee's pay.
  - `deduct_as_percentage` boolean — Whether the employee deduction amount should be treated as a percentage to be deducted from each payroll.
  - `employee_deduction_annual_maximum` string, nullable — The maximum employee deduction amount per year. A null value signifies no limit.
  - `effective_date` string, date — The date the employee benefit will start.
  - `expiration_date` string, date, nullable — The date the employee benefit will expire. A null value indicates the benefit will not expire.
  - `contribution` object — An object representing the type and value of the company contribution.
    - `type` 'amount' | 'percentage' | 'tiered' — The company contribution scheme. `amount`: The company contributes a fixed amount per payroll. If elective is true, the contribution is matching, dollar-for-dollar. `percentage`: The company contributes a percentage of the payroll amount per payroll period. If elective is true, the contribution is matching, dollar-for-dollar. `tiered`: The size of the company contribution corresponds to the size of the employee deduction relative to a tiered matching scheme.
    - `value` union — For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage. For the `tiered` contribution type, an array of tiers.
      - string — For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage.
      - object[] — For `tiered` contribution types, an array of tiers.
        - `rate` string — The percentage of employee deduction within this tier the company contribution will match.
        - `threshold` string — Specifies the upper limit (inclusive) percentage of the employee contribution that this tier applies to. Use threshold to define each tier's end point, with tiers applied cumulatively from 0% upwards. For example: If the first tier has a threshold of "3", and rate of "100", the company will match 100% of employee contributions from 0% up to and including 3% of payroll. If the next tier has a threshold of "5" and a rate of "50", the company will match 50% of contributions from above 3% up to and including 5% of payroll.
  - `elective` boolean — Whether the company contribution is elective (aka "matching"). For `tiered`, `elective_amount`, and `elective_percentage` contribution types this is ignored and assumed to be `true`.
  - `company_contribution_annual_maximum` string, nullable — The maximum company contribution amount per year. A null value signifies no limit.
  - `limit_option` 'Family' | 'Individual' | 'Joint Filing or Single' | 'Married and Filing Separately', nullable — Some benefits require additional information to determine their limit. `Family` or `Individual`: Applicable to HSA benefit. `Joint Filing or Single` or `Married and Filing Separately`: Applicable to Dependent Care FSA benefit.
  - `catch_up` boolean — Whether the employee should use a benefit's "catch up" rate. Only Roth 401k and 401k benefits use this value for employees over 50.
  - `coverage_amount` string, nullable — The amount that the employee is insured for. Note: company contribution cannot be present if coverage amount is set.
  - `deduction_reduces_taxable_income` 'unset' | 'reduces_taxable_income' | 'does_not_reduce_taxable_income', nullable — Whether the employee deduction reduces taxable income or not. Only valid for Group Term Life benefits. Note: when the value is not "unset", coverage amount and coverage salary multiplier are ignored.
  - `coverage_salary_multiplier` string — The coverage amount as a multiple of the employee's salary. Only applicable for Group Term Life benefits. Note: cannot be set if coverage amount is also set.
  - `company_contribution` string — The amount to be paid, per pay period, by the company.
  - `contribute_as_percentage` boolean — Whether the company contribution amount should be treated as a percentage to be deducted from each payroll.

## Response `200`

Example response

- EmployeeBenefit
  - `version` string — The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field.
  - `active` boolean — Whether the employee benefit is active.
  - `employee_deduction` string — The amount to be deducted, per pay period, from the employee's pay.
  - `deduct_as_percentage` boolean — Whether the employee deduction amount should be treated as a percentage to be deducted from each payroll.
  - `employee_deduction_annual_maximum` string, nullable — The maximum employee deduction amount per year. A null value signifies no limit.
  - `contribution` object — An object representing the type and value of the company contribution.
    - `type` string — The company contribution scheme. "amount": The company contributes a fixed amount per payroll. If elective is true, the contribution is matching, dollar-for-dollar. "percentage": The company contributes a percentage of the payroll amount per payroll period. If elective is true, the contribution is matching, dollar-for-dollar. "tiered": The company contribution varies according to the size of the employee deduction.
    - `value` union — For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage. For the `tiered` contribution type, an array of tiers.
      - string
      - object
        - `tiers` object[]
          - `rate` string — The percentage of employee deduction within this tier the company contribution will match.
          - `threshold` string — Specifies the upper limit (inclusive) percentage of the employee contribution that this tier applies to. Use threshold to define each tier's end point, with tiers applied cumulatively from 0% upwards. For example: If the first tier has a threshold of "3", and `rate` of "100", the company will match 100% of employee contributions from 0% up to and including 3% of payroll. If the next tier has a threshold of "5" and a rate of "50", the company will match 50% of contributions from above 3% up to and including 5% of payroll.
          - `threshold_delta` string — The step up difference between this tier's threshold and the previous tier's threshold. In the first tier, this is equivalent to threshold.
  - `elective` boolean — Whether the company contribution is elective (aka matching). For "tiered" contribution types, this is always true.
  - `company_contribution_annual_maximum` string, nullable — The maximum company contribution amount per year. A null value signifies no limit.
  - `limit_option` string, nullable — Some benefits require additional information to determine their limit. `Family` and `Individual` are applicable to HSA benefit. `Joint Filing or Single` and `Married and Filing Separately` are applicable to Dependent Care FSA benefit.
  - `catch_up` boolean, nullable — Whether the employee should use a benefit's "catch up" rate. Only Roth 401k and 401k benefits use this value for employees over 50.
  - `retirement_loan_identifier` string, nullable — Identifier for a 401(k) loan assigned by the 401(k) provider
  - `coverage_amount` string, nullable — The amount that the employee is insured for. Note: company contribution cannot be present if coverage amount is set.
  - `deduction_reduces_taxable_income` 'unset' | 'reduces_taxable_income' | 'does_not_reduce_taxable_income', nullable — Whether the employee deduction reduces taxable income or not. Only valid for Group Term Life benefits. Note: when the value is not "unset", coverage amount and coverage salary multiplier are ignored.
  - `coverage_salary_multiplier` string, nullable — The coverage amount as a multiple of the employee's salary. Only applicable for Group Term Life benefits. Note: cannot be set if coverage amount is also set.
  - `company_contribution` string — The amount to be paid, per pay period, by the company. This field will not appear for tiered contribution types.
  - `contribute_as_percentage` boolean — Whether the company_contribution value should be treated as a percentage to be added to each payroll. This field will not appear for tiered contribution types.
  - `effective_date` string, date — The date the employee benefit will start.
  - `expiration_date` string, date, nullable — The date the employee benefit will expire. A null value indicates the benefit will not expire.
  - `employee_uuid` string — The UUID of the employee to which the benefit belongs.
  - `company_benefit_uuid` string — The UUID of the company benefit.
  - `uuid` string, required — The UUID of the employee benefit.

## Other responses

- `404` — Not Found The requested resource does not exist. Make sure the provided UUID is valid.
- `422` — Unprocessable Entity This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.

---

[API](https://skmtc.net/gusto/apis/gusto-api.md) · [All operations](https://skmtc.net/gusto/apis/gusto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gusto/gusto-api/revisions/826dfa57fb3b/schema)