Working with Time Off Policies
Configure PTO and sick leave policies, track employee balances, and calculate accrual and usage on payroll
Overview
Check's Time Off API lets you track paid time off (PTO), sick leave, and any other kind of time off for employees, and have accrual and usage calculated automatically when you run payroll. With it, you can:
- Define time off policies that set how hours accrue, and the caps, rollover, and waiting periods that apply
- Track each employee's balances, such as PTO, Sick, or Parental Leave, and move them between policies without losing their history
- Calculate accrual and usage automatically when you run payroll
- Show a full statement of every change to a balance
Time off is four resources:
| Resource | ID prefix | What it is | Can be changed after create |
|---|---|---|---|
| Time Off Policy | top_ | A company's rules for how hours accrue. | status |
| Time Off Balance | tob_ | One bucket of an employee's hours, named by label. Starts at 0. | metadata |
| Time Off Enrollment | toenr_ | Puts a balance on a policy from effective_start to effective_end. | effective_end |
| Time Off Entry | toent_ | One positive or negative change to a balance. | Nothing |
Because the balance is separate from the policy, changing an employee's policy, such as a tenure-based tier upgrade or a mid-year move, is just a new enrollment. The balance and its history stay where they are.
All hour values are decimal strings, such as "40.00". Time off is always tracked in hours.
Setup at a glance
POST /time_off_policies { company, label, accrual_method, ... } → top_
POST /time_off_balances { employee, label: "PTO" } → tob_ hours: 0
POST /time_off_enrollments { balance, policy, effective_start } → toenr_
POST /time_off_entries { balance, hours: "24.00", source: "manual" } → toent_ opening balanceCreating a time off policy
Create a policy with a POST request to /time_off_policies. The example below gives employees 120 hours of PTO a year, accrued evenly across their regular payrolls, after a 90-day waiting period. Up to 80 unused hours roll over each year.
{
"company": "com_sx3svU6K8c5ZkSFlOh5p",
"label": "PTO — years 1-5",
"policy_year": { "basis": "fixed_date", "date": "01-01" },
"accrual_method": "per_payroll",
"annual_grant_options": null,
"per_payroll_options": { "hours_per_year": "120.00" },
"per_hour_worked_options": null,
"limits": {
"max_balance": null,
"min_balance": "0.00",
"max_rollover": "80.00",
"max_accrual_per_policy_year": null
},
"accrual_waiting_period_days": 90,
"usage_waiting_period_days": 120,
"metadata": {}
}A policy isn't tied to an earning type. The same policy can govern a PTO balance or a sick balance. Policies can't be edited after they're created, except to archive them with status. To change the rules, create a new policy and move balances to it with new enrollments.
Policy year
Every policy runs on an annual cycle, called the policy year. The policy year controls when annual grants are made, when max_accrual_per_policy_year resets, and when unused hours expire. Set policy_year.basis to one of:
fixed_date: the policy year starts on the same calendar date for every employee. Setpolicy_year.dateinMM-DDformat, such as"01-01"for a calendar year.enrollment: the policy year starts on the anniversary of the balance's first enrollment. Changing policies doesn't move the anniversary.
Accrual methods
accrual_method controls how hours accrue automatically. Set the options object that matches the method, and leave the others null.
accrual_method | Written by | When | Hours |
|---|---|---|---|
annual_grant | Daily job | The first day of the policy year, or effective_start for an enrollment that starts mid-year | hours, prorated or in full per partial_year_method |
per_payroll | Payroll | Each regular payroll. Off-cycle payrolls only with off_cycle_options.apply_time_off_policies set to true | hours_per_year ÷ pay periods per year |
per_hour_worked | Payroll | Each payroll | hours worked × hours ÷ per_hours_worked |
none | You | Anytime, as manual entries | Whatever you send |
Annual grant
{
"accrual_method": "annual_grant",
"annual_grant_options": {
"hours": "80.00",
"partial_year_method": "prorate"
}
}partial_year_method controls the grant for an enrollment that starts partway through a policy year. prorate grants a share of hours based on the days left in the policy year. full grants all of hours.
Per payroll
{
"accrual_method": "per_payroll",
"per_payroll_options": {
"hours_per_year": "120.00"
}
}An employee paid biweekly on this policy accrues 120 ÷ 26 = 4.62 hours on each regular payroll.
Per hour worked
{
"accrual_method": "per_hour_worked",
"per_hour_worked_options": {
"hours": "1.00",
"per_hours_worked": "30.00",
"include_overtime": false
}
}The employee accrues hours for every per_hours_worked hours worked on a payroll. Only worked earning types count as hours worked; time off and holiday hours never do. Overtime hours count only when include_overtime is true.
Limits
The limits object caps automatic accrual. Leave a limit null to not enforce it.
max_balance: The maximum balance an employee can hold. Automatic accrual is trimmed so the balance stays at or below this cap.min_balance: The minimum balance.max_rollover: The maximum number of unused hours that carry over into the next policy year. On the last day of the policy year, hours above this cap expire.max_accrual_per_policy_year: The maximum number of hours that can accrue automatically in one policy year.
Waiting periods
Waiting periods are counted in days from the balance's first enrollment. Changing policies doesn't restart them.
accrual_waiting_period_days: Nothing accrues until the waiting period ends. Per-payroll and per-hour-worked hours during the waiting period aren't banked. An annual grant that falls in the waiting period is written on the day it ends.usage_waiting_period_days: Spending hours before the waiting period ends returns a warning on the payroll item. It doesn't block approval.
Creating balances
A balance is one bucket of an employee's hours. Create one with a POST request to /time_off_balances:
{
"employee": "emp_sx3svU6K8c5ZkSFlOh5p",
"label": "PTO"
}New balances start at 0 hours. An employee can have any number of balances, told apart by label, such as PTO, Sick, and Parental Leave. Fetch a balance at any time with GET /time_off_balances/{balance}, or list an employee's balances with GET /time_off_balances:
{
"id": "tob_3kWm9Qz5Ht2Lp8Nv",
"employee": "emp_sx3svU6K8c5ZkSFlOh5p",
"label": "PTO",
"hours": "17.16",
"hours_as_of": "2026-10-20T00:00:00Z",
"metadata": {}
}hours is the sum of all entries on the balance. It changes only when an entry is written: when a payroll is approved, reopened, or voided; when the daily job writes an annual grant or expiration; or when you create a manual entry.
To set an opening balance, such as for an employee moving from another system, create a manual entry. See Creating manual entries.
Enrolling a balance in a policy
An enrollment puts a balance on a policy for a date range. Create one with a POST request to /time_off_enrollments:
{
"balance": "tob_3kWm9Qz5Ht2Lp8Nv",
"policy": "top_4fKq8Wz1mN2pR7sT",
"effective_start": "2026-03-12"
}effective_end is null by default, for an open-ended enrollment. Enrollments on the same balance can't overlap. A balance with no enrollment is valid: it only changes through payroll spend and manual entries.
If effective_start is today or earlier, creating the enrollment immediately writes any annual grant or expiration that's already due. The response is still the enrollment; fetch the balance for its updated hours.
Changing policies
To move a balance to a different policy, such as a tenure-based tier upgrade, set effective_end on the current enrollment with a PATCH request, then create the next enrollment:
tob_ PTO
toenr_1 "PTO — years 1-5" 2026-01-01 → 2026-12-31
toenr_2 "PTO — years 6+" 2027-01-01 → (open)The balance keeps its hours and history. For automatic accruals, the enrollment active on the entry's date picks the policy. If a policy changes partway through a pay period, per-payroll hours are split by days, with one entry per enrollment.
Ending an enrollment retroactively doesn't recalculate past entries. Adjust the balance with manual entries if needed.
Viewing the balance history
Every change to a balance is a Time Off Entry. List entries with a GET request to /time_off_entries, filtered by balance or employee, to show a full statement of accrual and spend.
{
"id": "toent_8hPq2Lm4Xk7Vn1Rt",
"balance": "tob_3kWm9Qz5Ht2Lp8Nv",
"employee": "emp_sx3svU6K8c5ZkSFlOh5p",
"enrollment": "toenr_7xBn2Kp9Rt4Wm1Qz",
"policy": "top_4fKq8Wz1mN2pR7sT",
"hours": "4.62",
"source": "payroll",
"payroll": "pay_KY1Kavi5D5kKyJLsp2uO",
"date": "2026-03-31",
"description": null,
"metadata": {}
}Positive hours add to the balance, and negative hours subtract from it. date is the date the entry counts for. source shows how the entry was created:
source | Description |
|---|---|
payroll | Hours accrued on a payroll for per_payroll or per_hour_worked policies, or hours spent as pto or sick earnings on a payroll. payroll is set to its ID. |
annual_grant | The grant on the first day of the policy year for annual_grant policies. |
expiration | A negative entry on the last day of the policy year, removing unused hours above the policy's max_rollover. |
manual | An entry you created. enrollment and policy are null. |
Entries can't be edited.
Creating manual entries
For changes that don't come from payroll, such as opening balances, transfers, adjustments, or accruals a policy doesn't model, create a manual entry with a POST request to /time_off_entries:
{
"balance": "tob_3kWm9Qz5Ht2Lp8Nv",
"hours": "24.00",
"source": "manual"
}Manual entries are written as sent.
Accrual and usage on payroll
Spending hours
To spend hours from a balance, include a pto or sick earning on the payroll item and set time_off_balance to the balance's ID. time_off_balance is only allowed on pto and sick earnings.
"earnings": [
{
"type": "hourly",
"hours": "72.00",
"amount": "1800.00",
"workplace": "wrk_cxcG4vjGKcSXZk1fgKai"
},
{
"type": "pto",
"hours": "8.00",
"amount": "200.00",
"workplace": "wrk_cxcG4vjGKcSXZk1fgKai",
"time_off_balance": "tob_3kWm9Qz5Ht2Lp8Nv"
}
]If time_off_balance is null or not set, the hours are paid but not tracked against any balance.
Accrual and resulting balances
Check calculates accrual from each balance's active enrollment on the pay period end. On preview and approval, the payroll item returns a read-only time_off_balances array with each balance the payroll accrues to or spends from, and its hours after the payroll:
"time_off_balances": [
{
"time_off_balance": "tob_3kWm9Qz5Ht2Lp8Nv",
"hours": "34.62"
}
]In this example, the balance started at 38.00 hours, accrued 4.62 hours, and spent 8.00 hours.
| Who provides it | Where it shows | |
|---|---|---|
| Spend | You, as a pto or sick earning with time_off_balance | earnings (input and output) |
| Accrual | Check, from the enrollment's policy | time_off_balances (output only) |
| Resulting balance | Check | time_off_balances (output only) |
To see the individual entries a payroll wrote, list entries filtered by payroll.
Payroll lifecycle
A payroll's time off entries, both accrual and spend, follow the payroll:
- Preview: entries are calculated but not saved.
- Approve: entries are written and balances are updated. Approval fails as stale if a balance changed after preview, including another payroll spending from it, or a grant or expiration from the daily job. Preview again before approving.
- Reopen: the payroll's entries are deleted.
- Void: when you void a payroll item, Check writes an offsetting entry for every entry the payroll item wrote. Later accruals aren't recalculated.
Off-cycle payrolls
per_payroll policies don't accrue on off-cycle payrolls by default. To accrue on an off-cycle, set off_cycle_options.apply_time_off_policies to true, like apply_benefits. per_hour_worked policies accrue on any payroll with hours worked.
Warnings
Time off warnings never block payroll approval, and spent hours are never reduced. You can enforce them in your own UI. Payroll items return:
time_off_balance_insufficient: the hours spent are more than the balance.time_off_spend_waiting_period_not_met: hours are spent before the policy'susage_waiting_period_dayshas passed.
{
"type": "time_off_balance_insufficient",
"resource_type": "time_off_balance",
"resource": "tob_3kWm9Qz5Ht2Lp8Nv",
"message": "8.00 hours were requested, but only 5.00 hours are available to spend. The requested hours have not been reduced.",
"deduction_adjustment": null
}Time off warnings use a new payroll item warning format, available in a new API version. Earlier API versions keep returning deduction warnings in today's format and don't return time off warnings.
The daily job
Once a day, Check writes the entries that don't come from payroll:
| Entry | Due on | Hours |
|---|---|---|
expiration | The last day of each policy year, for policies with max_rollover set | Minus the hours above max_rollover. Nothing is written if the balance is at or under it |
annual_grant | The first day of each policy year, or effective_start for a mid-year enrollment, or the day the accrual waiting period ends if that's later | hours, prorated or in full per partial_year_method, trimmed by limits |
Entries are dated with the due date, not the day the job runs. The job catches up on any due date that doesn't have an entry yet, so a backdated effective_start is picked up on the next run. It never writes the same entry twice. No grants or expirations are written after an enrollment's effective_end unless another enrollment covers the date.
For example, with a fixed_date policy year starting 01-01, an annual grant of 80 hours prorated, and a max_rollover of 40, for a balance enrolled on 2026-06-01:
2026-06-01 annual_grant +46.90 80 × 214/365 days left balance 46.90
(payroll spend) -20.00 balance 26.90
2026-12-31 expiration — under max_rollover balance 26.90
2027-01-01 annual_grant +80.00 balance 106.90
(payroll spend) -30.00 balance 76.90
2027-12-31 expiration -36.90 76.90 - 40 balance 40.00
2028-01-01 annual_grant +80.00 balance 120.00Rules for automatic accrual
These apply to entries Check writes from payroll and the daily job. Manual entries are written as sent.
- Caps: accrual is trimmed to stay within
max_balanceandmax_accrual_per_policy_year. If the whole accrual is trimmed, no entry is written. - Rounding: each entry is rounded to two decimal places.
- Expiration before grant: on a policy year boundary, the expiration is written before the next year's grant.
Updated about 4 hours ago

