--- 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}` ## Request - Base URL: `https://api.gusto-demo.com` - URL: `https://api.gusto-demo.com/v1/employee_benefits/{employee_benefit_id}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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.dev/gusto/apis/gusto-api.md) - [All operations](https://skmtc.dev/gusto/apis/gusto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gusto/apis/gusto-api/revisions/f98575fa2a5e?raw)