| state | No | Optional US state, e.g. CA, for an informational note on state paid sick leave accrual rules. | |
| pay_date | No | Any real payday for weekly or biweekly pay, e.g. 2026-01-09, so accruals land on the right Fridays. Default: the first Friday on or after the ledger start. | |
| hire_date | No | Hire (start) date, e.g. 2024-03-04. Used for tenure tiers, the waiting period and the first partial pay period. | |
| as_of_date | No | Date to report the balance on, e.g. 2026-10-26. Default: today in US Eastern time. | |
| first_year | No | For annual_front_loaded: prorated (default, first grant prorated by days left in the year) or full. | |
| hours_used | No | Total PTO hours used without dates, e.g. 40 for "I used 40 hours this year". Subtracted on the as-of date. Use time_taken when dates are known. | |
| reset_date | No | When the accrual year resets (carryover is applied), e.g. "01-01" (default January 1), "July 1", or "anniversary" (hire anniversary), or "none". | |
| time_taken | No | PTO used or planned, as a list [{"date":"2026-03-02","hours":8}] or text "2026-03-02 8h, 2026-07-06 to 2026-07-10, Dec 24 4h". Future dates count as planned time off in the projection. | |
| accrual_per | No | How often accrual_amount is earned: year, month, week, pay_period, or hour_worked. Required for hours; days or weeks without it are read as per year. | |
| annual_days | No | Days of PTO per year, e.g. 15. Converted with hours_per_day (default 8). | |
| max_balance | No | Maximum balance (accrual stops at this cap until hours are used), in hours, e.g. 240, or "30 days". | |
| accrual_rate | No | Fallback only, when you cannot fill accrual_amount/accrual_unit/accrual_per: the rule as text with a number, unit and period, e.g. "1 per 30", "4.62 hours per paycheck", "15 days a year". Hours without a period are refused. | |
| accrual_unit | No | Unit of accrual_amount: hours (default), days, or weeks (weeks = days_per_week x hours_per_day). | |
| annual_hours | No | Hours of PTO per year, e.g. 120. Use instead of annual_days. | |
| hours_worked | No | Actual hours worked per pay period for per_hour_worked, e.g. [{"date":"2026-01-09","hours":72}] or "2026-01-09: 72, 2026-01-23: 80". Periods not listed use the standard hours. | |
| tenure_tiers | No | Tenure tiers (years of service), as text "0-2: 10 days, 3-5: 15 days, 6+: 20 days" or a list [{"from_year":0,"annual_days":10},{"from_year":3,"annual_days":15}]. "years 3-5" starts at the 3rd work anniversary. | |
| days_per_week | No | Workdays per week, default 5. Converts weeks of PTO to hours. | |
| employee_name | No | Optional name for the ledger header, e.g. Dana Kim. | |
| hours_per_day | No | Hours in one PTO day, default 8, e.g. 7.5. | |
| pay_frequency | No | Pay schedule: weekly, biweekly (default, every two weeks), semimonthly (15th and last day), or monthly. | |
| accrual_amount | No | Preferred way to give the rule: the amount earned, e.g. 15 (with accrual_unit days, accrual_per year), 4.62 (hours per pay_period) or 0.0333 (hours per hour_worked). | |
| accrual_method | No | How PTO is earned: per_hour_worked (e.g. 1 h per 30 h worked), per_pay_period (fixed hours each paycheck, e.g. 4.62 h), annual_front_loaded (whole year granted at once on the reset date), annual_accrued_per_period (yearly amount, e.g. 15 days, spread evenly over pay periods). Optional: inferred from the other fields. | |
| hours_per_week | No | Standard hours per week, default 40, e.g. 30 for part time. Used when hours worked are not given. | |
| waiting_period | No | Waiting period after hire before PTO can be used, e.g. "90 days" or "3 months". | |
| carryover_limit | No | Hours that may roll over at the reset date, e.g. 40. 0 = use it or lose it. Leave out for unlimited rollover. | |
| starting_balance | No | Known balance on starting_balance_date, in hours, e.g. 32.5 (from a pay stub), or "4 days". | |
| annual_accrual_cap | No | Most hours that can be earned in one accrual year, e.g. 48. | |
| waiting_period_rule | No | accrue_but_locked (default: hours accrue from hire but cannot be used until the waiting period ends) or no_accrual (nothing accrues during the waiting period). | |
| starting_balance_date | No | Date of the starting balance, e.g. 2026-01-01. Default: the start of the current accrual year (or the hire date if later). | |
| hours_worked_per_period | No | Hours worked in each pay period, for per_hour_worked when it differs from the standard (40 h/week), e.g. 64. | |