Create a holiday pay policy

In addition to Vacation and Sick time off policies, Gusto Embedded offers the ability to create and manage holiday pay policies.

For each available holiday, a company can set whether or not it is paid. When a company sets a holiday as paid, the system automatically pushes its hours into all applicable payrolls.

What are holiday pay policies?

When using holiday pay policies there are two use cases:

Passing holiday hours tracked through the Partner application into the Gusto payroll system.
1. For this use case: you must create the holiday policy and set all holidays to not be paid. Then when it's time to process payroll, sync over any holiday hours to the Holiday Hours payroll item under the "paid_time_off" array.
Gusto defines holidays and automatically pushes hours for those holidays into the applicable payrolls
1. For this use case: we have the following holidays available via the Gusto API and you will set specific holidays to be paid out automatically to employees.

Supported holidays

New Year’s Day
Martin Luther King, Jr. Day
Presidents’ Day
Memorial Day
Juneteenth
Independence Day
Labor Day
Columbus Day
Veterans Day
Thanksgiving
Christmas Day

Once the days are configured the holiday pay hours will automatically be included in the payroll item.

📘
A company is allowed one holiday pay policy at a time.

Response body structure

All holiday pay policy endpoints (besides delete and preview) will return the same response body when correctly used. This response will contain:

version - the policy’s current version identifier
company_uuid - the UUID of the company to which the policy belongs
federal_holidays - describes the policy for the eleven supported holidays, with each holiday containing the following:
- holiday_key - such as “new_years_day” or “thanksgiving”
  - selected - true (the holiday is paid) or false (the holiday is not paid)
  - name - the official name of the holiday (e.g. “New Year’s Day” or “Thanksgiving”)
  - date - the date of the holiday (e.g. “January 1” or “Fourth Thursday in November”)
employees - an array of the employee uuids of the employees enrolled in the policy

Get a holiday pay policy

To fetch a holiday policy use the GET companies/{company_uuid}/holiday_pay_policy endpoint.

Sample request

curl --request GET \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/holiday_pay_policy \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_token}}' \
     --header 'content-type: application/json' \

📘
If the company does not have a holiday pay policy, the endpoint will return 204 No Content.

Create a holiday pay policy

Define a holiday pay policy for an existing company with the POST companies/{company_uuid}/holiday_pay_policy endpoint. If the company already has a holiday pay policy, the endpoint will return an error.

Holiday selections can be optionally passed as body parameters. Any holidays that are not passed will be set as unpaid.

Sample request

curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/holiday_pay_policy \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_token}}' \
     --header 'content-type: application/json' \
     --data '
{
	“federal_holidays”: {
		“new_years_day”: {
			“selected”: true
		},
		“veterans_day”: {
			“selected:” true
		}
}
'

Sample response

{
  "version": {policy_version},
	"company_uuid": {company_uuid},
  "federal_holidays": {
    "new_years_day": {
      "selected": true,
      "name": "New Year's Day",
      "date": "January 1"
    },
    "mlk_day": {
      "selected": false,
      "name": "Martin Luther King, Jr. Day",
      "date": "Third Monday in January"
    },
    "presidents_day": {
      "selected": false,
      "name": "Presidents' Day",
      "date": "Third Monday in February"
    },
    "memorial_day": {
      "selected": false,
      "name": "Memorial Day",
      "date": "Last Monday in May"
    },
    "juneteenth": {
      "selected": false,
      "name": "Juneteenth",
      "date": "June 19"
    },
    "independence_day": {
      "selected": false,
      "name": "Independence Day",
      "date": "July 4"
    },
    "labor_day": {
      "selected": false,
      "name": "Labor Day",
      "date": "First Monday in September"
    },
    "columbus_day": {
      "selected": false,
      "name": "Columbus Day (Indigenous Peoples' Day)",
      "date": "Second Monday in October"
    },
    "veterans_day": {
      "selected": true,
      "name": "Veterans Day",
      "date": "November 11"
    },
    "thanksgiving": {
      "selected": false,
      "name": "Thanksgiving",
      "date": "Fourth Thursday in November"
    },
    "christmas_day": {
      "selected": false,
      "name": "Christmas Day",
      "date": "December 25"
    }
  },
	"employees": []
}

Preview paid holidays

Once a holiday pay policy is defined for a specific company, you can preview upcoming paid holidays with the GET companies/{company_uuid}/paid_holidays endpoint.

Holidays are created for the next three years. If a year is passed as a body param, only holidays for that year will be returned. Otherwise, holidays for the next three years will be returned. The response will contain a list of holidays, each containing the key, name, start date, and end date of the holiday.

Sample request

curl --request GET 'https://api.gusto-demo.com/v1/companies/{company_uuid}/paid_holidays' \
--header 'Authorization: Bearer COMPANY_API_TOKEN' \
--header 'X-Gusto-API-Version: 2025-06-15' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "year": "2026"
}'

Sample response

[
    {
        "holiday_key": "new_years_day",
        "holiday_name": "New Year's Day",
        "start_date": "2026-01-01",
        "end_date": "2026-01-01"
    },
    {
        "holiday_key": "veterans_day",
        "holiday_name": "Veterans Day",
        "start_date": "2026-11-11",
        "end_date": "2026-11-11"
    }
]

Update a holiday pay policy

Update a holiday policy using the PUT companies/{company_uuid}/holiday_pay_policy endpoint.

📘
Just like when defining the policy, holiday selections are passed as body parameters. Any holidays that are not passed will be set as unpaid, so make sure to specify all desired paid holidays in the request body.
In addition, only holiday selections can be updated using this endpoint, as holiday names and dates are non-configurable.

Sample request

curl --request PUT \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/holiday_pay_policy \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_token}}' \
     --header 'content-type: application/json' \
     --data '
{
  "version": {policy_version},
	“federal_holidays”: {
		“new_years_day”: {
			“selected”: true
		},
		“veterans_day”: {
			“selected:” true
    },
		“thanksgiving”: {
			“selected:” true
    },
		“christmas_day”: {
			“selected:” true
    },
  }
}
'

Sample response

{
  "version": {policy_version},
	"company_uuid": {company_uuid},
  "federal_holidays": {
    "new_years_day": {
      "selected": true,
      "name": "New Year's Day",
      "date": "January 1"
    },
    "mlk_day": {
      "selected": false,
      "name": "Martin Luther King, Jr. Day",
      "date": "Third Monday in January"
    },
    "presidents_day": {
      "selected": false,
      "name": "Presidents' Day",
      "date": "Third Monday in February"
    },
    "memorial_day": {
      "selected": false,
      "name": "Memorial Day",
      "date": "Last Monday in May"
    },
    "juneteenth": {
      "selected": false,
      "name": "Juneteenth",
      "date": "June 19"
    },
    "independence_day": {
      "selected": false,
      "name": "Independence Day",
      "date": "July 4"
    },
    "labor_day": {
      "selected": false,
      "name": "Labor Day",
      "date": "First Monday in September"
    },
    "columbus_day": {
      "selected": false,
      "name": "Columbus Day (Indigenous Peoples' Day)",
      "date": "Second Monday in October"
    },
    "veterans_day": {
      "selected": true,
      "name": "Veterans Day",
      "date": "November 11"
    },
    "thanksgiving": {
      "selected": true,
      "name": "Thanksgiving",
      "date": "Fourth Thursday in November"
    },
    "christmas_day": {
      "selected": true,
      "name": "Christmas Day",
      "date": "December 25"
    }
  },
	"employees": []
}

Delete a holiday pay policy

Delete a holiday policy using the DELETE companies/{company_uuid}/holiday_pay_policy endpoint.

curl --request DELETE \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/holiday_pay_policy \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_token}}' \
     --header 'content-type: application/json' \'

If the company does not have a policy, the endpoint will return an error. Otherwise, it will return 204 No Content.

Manage employees assigned to a holiday pay policy

To add employees to a holiday policy use the PUT companies/{company_uuid}/holiday_pay_policy/add endpoint.

To remove employees to a holiday policy use the PUT companies/{company_uuid}/holiday_pay_policy/remove endpoint.

📘
Note that adding and removing employees does so to the entire policy, as opposed to individual holidays.

The following path params are required:

company_uuid - the uuid of the company for which you’d like to fetch a holiday pay policy.

The following body params are required:

version - the policy’s current version identifier. This can be acquired by fetching the policy.
employees - an array of the employees you wish to add to or remove from the policy

Sample request (adding an employee to a holiday pay policy)

curl --request PUT \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/holiday_pay_policy/add \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_token}}' \
     --header 'content-type: application/json' \'
          --data '
{
     "employees": [
          {
               "uuid": "56c672b4-3918-45cd-a3bb-a62ae0ff1307"
          },
          {
               "uuid": "28e7a45d-32dd-4925-a82a-9a3ccc6d302c"
          }
     ]
}
'

If the company does not have a policy, the endpoint will return an error. Otherwise, the endpoint will return the response body as outlined in this earlier section.