Guides

Manage company benefits

Learn how to create and assign company benefits, and manage contribution exclusions

Suggest Edits

Company benefits are the specific benefits a company offers to its employees.

Each benefit connects a supported benefit type, such as health insurance or commuter perks, with company-specific settings, including how costs are shared between the employer and the employee.

The benefit object in Gusto contains high-level information about a particular benefit type and its tax considerations. When companies choose to offer a benefit, they create a Company Benefit object associated with that benefit.

After creating a company benefit and assigning employees, Gusto will automatically factor in company contributions and employee deductions in payroll calculations. At this time Gusto does not remit or pay contributions/deductions to the respective benefit provider—this must be managed by the employer.

Creating a company benefit

Before using this guide you must have created a company. You can learn more by following the Onboard a company guide.

1. Get supported benefits

To get a list of all supported benefits, use the GET v1/benefits endpoint. The endpoint will return an array of company benefit objects, which have the following structure: 

{
  "benefit_type": 1,
  "name": "Medical Insurance",
  "description": "Deductions and contributions for Medical Insurance",
  "pretax": true,
  "posttax": false,
  "imputed": false,
  "healthcare": true,
  "retirement": false,
  "yearly_limit": false,
  "category": "Health"
}

2. Create a company benefit

Using the benefit_type of the benefit you want to add from the previous step, you can now create the company benefit with the POST /companies/{company_uuid}/company_benefits endpoint

This endpoint requires a more specific description, such as “Kaiser Permanente” or “Blue Cross/Blue Shield”.

curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/company_benefits \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_API_TOKEN>>' \
     --header 'content-type: application/json' \
     --data '
{
     "active": true,
     "benefit_type": 1,
     "description": "Blue Cross/ Blue Shield",
     "responsible_for_employer_taxes": false,
     "responsible_for_employee_w2": false
}
'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/company_benefits';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    active: true,
    benefit_id: 1,
    description: 'Blue Cross/ Blue Shield',
    responsible_for_employer_taxes: false,
    responsible_for_employee_w2: false
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Sample response

{
	"uuid": "COMPANY_BENEFIT_UUID",
	"version": "VERSION",
	"company_uuid": "COMPANY_UUID",
	"benefit_type": 1,
	"description": "Blue Cross/Blue Shield",
	"active": true,
	"responsible_for_employer_taxes": false,
	"responsible_for_employee_w2": false,
	"deletable": true,
	"source": "external",
	"partner_name": "ABC Organization",
	"supports_percentage_amounts": false
}

3. (Optional) Confirm benefit creation

You can always see what benefits a company has, including any new benefits, by calling the GET /companies/{company_uuid}/company_benefits endpoint.

curl --request GET \
     --url 'https://api.gusto-demo.com/v1/companies/{company_uuid}/company_benefits?enrollment_count=true' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_API_TOKEN>>'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/company_benefits?enrollment_count=true';
const options = {
  method: 'GET',
  headers: {accept: 'application/json', authorization: 'Bearer <<COMPANY_API_TOKEN>>'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

4. (Optional) Add contribution exclusions

You can add contribution exclusions for 401(k) and Roth 401(k) company benefits. To do this:

  1. Call the GET /company_benefits/{company_benefit_id}/contribution_exclusionsendpoint, which returns an array of contributions for the given company benefit.

    For example the response might look like:

    [
  {  
    "contribution_uuid": "b82e35c5-d7c6-4705-9e16-9f87499ade18",  
    "contribution_type": "Bonus",  
    "excluded": false  
  },  
  {  
    "contribution_uuid": "f5618c94-ed7d-4366-b2c4-ff05e430064f",  
    "contribution_type": "Cash Tips",  
    "excluded": false  
  },  
  {  
    "contribution_uuid": "60191999-004a-49d9-b163-630574433653",  
    "contribution_type": "Commission",  
    "excluded": false  
  },  
  {  
    "contribution_uuid": "75a7a827-1f2d-4d6f-94f2-514c1fc32b13",  
    "contribution_type": "Regular",  
    "excluded": false  
  },  
  {  
    "contribution_uuid": "eead3c7c-7964-4e3c-b609-670456127b09",  
    "contribution_type": "Life insurance imputed benefit",  
    "excluded": true  
  }  
]

  1. Determine the contribution types you want to exclude or include from company contributions.

  2. Call thePUT company_benefits/{company_benefit_id}/contribution_exclusions endpoint, which takes as body params the array of contribution types in the same structure as when you listed the company benefit’s contribution exclusions.

    Set "excluded": true for contribution types you want to exclude and "excluded": false for contribution types you want included.

    For example, your request might look like this:

    curl --request PUT \
     --url https://api.gusto-demo.com/v1/company_benefits/company_benefit_id/contribution_exclusions \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "contribution_exclusions": [
    {
      "excluded": true,
      "contribution_type": "Bonus",
      "contribution_uuid": "b82e35c5-d7c6-4705-9e16-9f87499ade18"
    },
    {
      "excluded": false,
      "contribution_uuid": "f5618c94-ed7d-4366-b2c4-ff05e430064f",
      "contribution_type": "Cash Tips"
    }
  ]
}
'

5. Add benefits to employee

To assign a company benefit to an employee, you must create the benefit at the employee level using the POST employees/{employee_uuid}/employee_benefits endpoint.

When creating the benefit, you will specify the company contribution AND/OR the employee deduction amount.

curl --request POST \
     --url https://api.gusto-demo.com/v1/employees/{employee_uuid}/employee_benefits \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_API_TOKEN>>' \
     --header 'content-type: application/json' \
     --data '
{
     "active": true,
     "employee_deduction": "100.00",
     "deduct_as_percentage": false,
     "contribution": {
          "type": "amount",
          "value": "100.00"
     },
     "elective": false,
     "catch_up": false,
     "coverage_salary_multiplier": "0.00",
     "company_benefit_uuid": "f68abb42-431e-4392-bc3f-2795627e00f3"
}
'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/employees/{employee_uuid}/employee_benefits';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    active: true,
    employee_deduction: '100.00',
    deduct_as_percentage: false,
    contribution: {type: 'amount', value: '100.00'},
    elective: false,
    catch_up: false,
    coverage_salary_multiplier: '0.00',
    company_benefit_uuid: 'f68abb42-431e-4392-bc3f-2795627e00f3'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Consider company contribution exclusions

Percentage-based company contributions are calculated as the [contribution percentage] * (the sum of all non-excluded contribution types).

Example

Let's say that you enroll an employee in a 401(k) benefit with a company contribution percentage of 10%. This employee earns pay of these types: regular, bonus, overtime, an imputed benefit, and time off pay, and there are company contribution exclusions for bonus and time off pay.

The company contributions would be 10% * (regular + overtime + imputed benefit).

Fixed amount contributions with exclusions

Fixed amount company contributions are calculated as the [contribution amount] - (the sum of the excluded contribution types).

📘

If you create an employee benefit with a fixed company contribution amount, it’s possible that the fixed amount will not be met depending on the contribution exclusions on that company benefit.

Updated 10 days ago