Leave, PTO Accrual & Holidays

This guide covers everything time-off in Punchwell: defining leave types and the approval workflow, turning on PTO accrual (so balances build up automatically), loading your holiday calendar in one click, and letting employees request leave and check their own balances.

Everything here is opt-in. A fresh or freshly upgraded site behaves the same as before until you configure it — so you can roll out leave and PTO at your own pace.

Where this lives: Leave types, holidays, and the work week are under Punchwell → Leave. PTO accrual policies and balances are under Punchwell → Time Off. Employees use the front-end self-service widgets (see Employee Self-Service).

---

1. Before you start: set the Financial Year

Leave balances and the holiday calendar are scoped to your financial (fiscal) year, so set it before you load holidays or turn on accrual.

1. Go to Punchwell → Settings → General.
2. Set your fiscal-year start. On new installs this defaults to January 1. (If you migrated from the original plugin or an older Punchwell build, the legacy default was July 1 — confirm it matches your real fiscal year.)
3. Save.

A holiday lands in whichever financial year is current when you import it, and PTO carryover is calculated at the year boundary. Setting this first saves you re-doing work later. See Settings & Configuration for the full Settings hub.

---

2. Leave types

A leave type is a category of time off — Annual, Sick, Unpaid, Bereavement, and so on. You define them once; employees pick from them when requesting time off.

To create a leave type:

1. Go to Punchwell → Leave → Leave Types.
2. Click Add.
3. Enter:
   • Name (e.g. “Annual Leave,” “Sick”).
   • Yearly entitlement — how many days the type allows per financial year.
   • Departments — which teams the type applies to.
4. Save.

Good to know:

• You can’t delete a leave type once someone has taken leave under it. This is by design — deleting it would orphan history. Punchwell soft-deletes types instead (marks them inactive) so old records stay intact.
• The yearly entitlement on the leave type is the classic, simpler model: a fixed annual allowance. If you want balances to build up over time instead (and to draw down automatically when leave is approved), use PTO accrual in section 4 — it layers on top of the same leave types.

Migrating from the original plugin? Leave-type names carry over, but you’ll need to re-enter each type’s yearly entitlement under Punchwell → Leave → Leave Types. See the Migration Guide for the full data-migration steps.

---

3. The approval workflow

Punchwell uses a simple request-and-approve flow:

1. An employee requests leave — picks a leave type, a date range, and an optional reason. (They can do this in the admin app or, more commonly, from a front-end self-service page — see section 7.)
2. A manager or admin reviews it — Approve or Reject. Managers need the manage_leave capability; admins always qualify.
3. Approved leave takes effect — the employee is no longer marked absent on those dates, and if the type is set up for paid PTO accrual, the balance is drawn down automatically (section 4).

Who can do what:

Role	Can do
Employee	Request leave; withdraw their own pending request (cancel before it’s decided).
HR Manager (hrm_manager / manage_leave)	Approve or reject requests; reverse an already-approved request.
Admin	Everything, for everyone.

An employee can cancel a request only while it’s still pending. Once it’s approved, only a manager or admin can reverse it. The front-end approvals inbox is office-scoped: a manager assigned to an office sees only requests from employees in that office; admins and managers with no assigned office see all pending requests.

The Work Week. Under Punchwell → Leave → Work Week, set which days count as weekends. This tells Punchwell which days are working days, so leave-day counts and “absent” marking are accurate. Set it once.

---

4. PTO accrual

PTO accrual is a dedicated engine (Hrm_PTO) that builds up each employee’s paid-time-off balance automatically — instead of a flat yearly allowance, hours accumulate as time passes or as people work. It records a ledger of every earn, draw, and adjustment, and draws the balance down automatically when paid leave is approved.

Accrual is configured per leave type, and everything defaults to “None” — with no policy set, nothing accrues and behavior is unchanged.

Accrual amounts are always in HOURS. A single day of leave draws down your configured workday hours (default 8, set under Punchwell → Settings → General). So a 5-day approved leave on an 8-hour workday subtracts 40 hours from the balance.

Setting up an accrual policy

1. Go to Punchwell → Time Off.
2. You’ll see a row for each leave type. For the type you want to accrue:
   • Mark it Paid (only paid types draw down the balance; unpaid types are ignored by accrual).
   • Choose a Method (see below).
   • Fill in the amount fields, caps, and waiting period.
3. Save.

The three methods

Method	What it does	Amount field used
None	No accrual (default).	—
Accrue over time (incremental)	Builds the balance up gradually, on a cadence.	Annual hours or per-hour rate
Lump sum (annual)	Grants the full annual amount once at the start of each accrual year.	Annual hours

When you choose Accrue over time, pick a cadence:

• Monthly — earns Annual hours ÷ 12 each month. (Example: 96 annual hours → 8 hours/month.)
• Per hour worked — earns a set number of hours for each hour the employee actually works. (Example: a 0.0385 per-hour rate ≈ one hour of PTO for every 26 hours worked.) This reads real worked hours from attendance, so it suits hourly and part-time staff.

Caps, carryover, and the waiting period

Each policy also supports:

• Max balance — the ceiling a balance can reach. Accrual stops adding once the cap is hit. 0 = no cap.
• Carryover cap — how many hours roll into the new fiscal year. Leave it blank for unlimited carryover; enter a number to cap it; enter 0 so nothing carries over (a “use it or lose it” policy). Any excess is forfeited once, at the year boundary.
• Waiting period (days) — a probation window after the hire date before accrual begins. Nothing accrues until the hire date plus this many days. 0 = accrue from day one.

How accrual runs

The accrual engine runs automatically once a day (on Punchwell’s daily maintenance task). It is idempotent and self-correcting — each accrual, grant, and carryover event is keyed so it can’t be double-counted, and it back-fills any missed periods (for example after a stretch where the daily task didn’t run). You can also force it from Punchwell → Time Off with Run accrual now.

Hosts with WP-Cron disabled may not run the daily task on schedule. If balances look stale, use Run accrual now or ensure a real cron job is calling wp-cron.php.

How drawdown works

When a paid leave request is approved, Punchwell subtracts leave days × workday hours from that employee’s balance and records it in the ledger. If the request is later cancelled or its status reversed, the drawdown is released (added back). Multi-day requests are handled correctly. Unpaid leave types never touch a balance.

---

5. Holiday calendar

Holidays are company-wide non-working days (public holidays, company closures). On a holiday, employees aren’t expected to punch and aren’t marked absent.

To add holidays one at a time: Punchwell → Leave → Holiday → add a name and date.

For a whole year at once, use the importer in the next section — it’s much faster.

---

6. One-click holiday import

Instead of adding dates one by one, Punchwell → Holiday Import loads a full set of holidays three ways. All three show a preview before saving — each row is marked New, Duplicate, or Invalid, and duplicates are skipped automatically, so it’s safe to re-run.

Holiday Import is Administrator or HR-manager only. All dates are computed locally on your own server — no internet connection is used and nothing is sent anywhere, in keeping with Punchwell’s no-data-call-home design.

Option A — Country preset

1. Choose a country (US, UK, Canada, Australia, and more).
2. Choose a year.
3. Punchwell fills in that country’s public holidays in one click.

Option B — iCal (.ics) upload

1. Export a calendar to an .ics file — for example Google Calendar’s “Holidays in .”
2. Upload it. Its all-day events become holidays.

Option C — Paste a list

Paste one holiday per line:

2026-07-04, Independence Day
2026-12-24 to 2026-12-26, Winter Break

Use to for a multi-day range, as shown.

After choosing any option: review the preview, then click Add to apply.

Tip: a holiday lands in whichever financial year is current when you import. If you’re loading a future year’s holidays, set your Financial Year first.

---

7. Employee self-service

Most companies let staff request leave and check balances from a normal web page, without ever entering wp-admin. That’s handled by the Punchwell Front-End add-on, which provides shortcodes (each also available as a Gutenberg block). See Front-End & Self-Service for setup.

Shortcode	What the employee sees
[hrm_leave_request]	A leave-request form (type, dates, reason) plus a “My requests” table (Pending / Approved / Rejected). Pending requests show a Cancel button so the employee can withdraw their own request. Balances per leave type appear alongside the form.
[hrm_my_timeoff]	The employee’s own PTO balances by leave type — accrued / used / remaining. Read-only, own data only.
[hrm_approvals]	A manager’s leave inbox of pending requests they’re allowed to approve or reject. Office-scoped (see section 3). Requires the manage_leave capability.
[hrm_holidays]	An upcoming-holidays list. Options: show="upcoming|all", year="YYYY", limit="N".

[hrm_leave_request]‘s self-cancel feature requires base 2.13.1 or newer — the release that added a capability gate to the request-delete endpoint. Keep your base plugin current.

---

8. Recommended setup order

1. Set the Financial Year (Settings → General).
2. Create your leave types with yearly entitlements (Punchwell → Leave → Leave Types).
3. Set the Work Week (which days are weekends).
4. Import holidays for the current (and next) financial year (Punchwell → Holiday Import).
5. (Optional) Turn on PTO accrual per leave type (Punchwell → Time Off) — choose method, amounts, caps, carryover, waiting period; then Run accrual now.
6. Publish the self-service page so staff can request leave and view balances (Punchwell Front-End add-on).

---

FAQ

What’s the difference between a leave type’s “yearly entitlement” and PTO accrual? The yearly entitlement is a flat annual allowance on the leave type. PTO accrual is the smarter, automatic model: balances build up over time (monthly, per hour worked, or as an annual lump sum), are capped/carried over per your policy, and are drawn down automatically when paid leave is approved — with a ledger of every change. Accrual is configured per leave type under Punchwell → Time Off and is opt-in.

Can an employee cancel a leave request they already submitted? Yes — but only while it’s still pending. Once a manager has approved it, only a manager or admin can reverse it. Cancellation from the front end uses [hrm_leave_request] and requires base 2.13.1+.

Why can’t I delete a leave type? Because leave has already been taken under it. Deleting it would orphan that history, so Punchwell blocks it and soft-deletes (deactivates) the type instead — your records stay intact.

Does the holiday importer need internet access? No. Country presets are computed locally on your server, and iCal/paste imports read the file or text you provide. Nothing is sent anywhere — consistent with Punchwell’s no-data-call-home design.

How is a “day” of leave converted to hours for PTO drawdown? By your workday hours setting (Punchwell → Settings → General, default 8). A 3-day approved leave on an 8-hour workday draws 24 hours from the balance.

What does a blank vs. 0 carryover cap mean? Blank = unlimited carryover (the whole balance rolls into the new fiscal year). A number caps the hours carried over; the rest is forfeited at year-end. 0 means nothing carries over — a “use it or lose it” policy.

My accrual balances look out of date — what happened? Accrual runs on the daily maintenance task, which depends on WordPress cron. On hosts where WP-Cron is unreliable, use Run accrual now in Punchwell → Time Off, or set up a real server cron job to hit wp-cron.php. The engine back-fills any missed periods when it runs, so balances self-correct.

---

Related: Settings & Configuration · Front-End & Self-Service · Migration Guide · Attendance & Time Clock