Working with Time Off Policies

Configure PTO and sick leave policies, track employee balances, and calculate accrual and usage on payroll

🚧

Sandbox beta only

The Time Off API is in beta and is only available in Sandbox.

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:

  1. Define time off policies that set how hours accrue, and the caps, rollover, and waiting periods that apply
  2. Track each employee's balances, such as PTO, Sick, or Parental Leave, and move them between policies without losing their history
  3. Calculate accrual and usage automatically when you run payroll
  4. Show a full statement of every change to a balance

Time off is four resources:

ResourceID prefixWhat it isCan be changed after create
Time Off Policytop_A company's rules for how hours accrue.status
Time Off Balancetob_One bucket of an employee's hours, named by label. Starts at 0.metadata
Time Off Enrollmenttoenr_Puts a balance on a policy from effective_start to effective_end.effective_end
Time Off Entrytoent_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 balance

Creating 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. Set policy_year.date in MM-DD format, 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_methodWritten byWhenHours
annual_grantDaily jobThe first day of the policy year, or effective_start for an enrollment that starts mid-yearhours, prorated or in full per partial_year_method
per_payrollPayrollEach regular payroll. Off-cycle payrolls only with off_cycle_options.apply_time_off_policies set to truehours_per_year ÷ pay periods per year
per_hour_workedPayrollEach payrollhours worked × hours ÷ per_hours_worked
noneYouAnytime, as manual entriesWhatever 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:

sourceDescription
payrollHours 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_grantThe grant on the first day of the policy year for annual_grant policies.
expirationA negative entry on the last day of the policy year, removing unused hours above the policy's max_rollover.
manualAn 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 itWhere it shows
SpendYou, as a pto or sick earning with time_off_balanceearnings (input and output)
AccrualCheck, from the enrollment's policytime_off_balances (output only)
Resulting balanceChecktime_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's usage_waiting_period_days has 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:

EntryDue onHours
expirationThe last day of each policy year, for policies with max_rollover setMinus the hours above max_rollover. Nothing is written if the balance is at or under it
annual_grantThe 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 laterhours, 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.00

Rules 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_balance and max_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.

Did this page help you?