Shift Swaps

Employees can swap shifts with colleagues. Swaps are bilateral exchanges (A's shift ↔ B's shift). For unilateral handoffs — where you simply give your shift away — see Shift Offers.

Swap Workflow

The swap process is up to four stages, but the supervisor step usually doesn't fire:

1. Employee A requests a swap. They select one of their own shifts and the target shift they want to swap with.
2. Employee B accepts or rejects. The target employee reviews the proposed swap and decides whether to accept.
3. Compliance is checked at the moment of acceptance. The system simulates both employees in their post-swap shifts and runs the full compliance suite. If compliance passes, the swap auto-approves immediately and both shifts are reassigned. No supervisor click is required on the happy path.
4. Supervisor reviews — only when compliance flags a violation. When the auto-approve check fails, the swap stays at "Accepted" and a notification goes to managers with the violation list. The supervisor can override and approve the swap manually if appropriate.

Swap Statuses

Status	Description
Pending	Employee A has requested the swap. Waiting for Employee B to respond.
Accepted	Employee B has agreed but compliance flagged a violation, so the swap is parked for supervisor review.
Approved	Either auto-approved at acceptance (clean compliance), or approved by a supervisor override. Shifts have been swapped.
Rejected	Either Employee B or the supervisor rejected the swap.
Cancelled	Employee A withdrew the request before it was completed.

The happy path goes Pending → Approved in a single Accept click. The Accepted status only appears when compliance fails and a supervisor needs to review.

Reviewing Swap Requests

The list is accessible at Shift Swaps in the navigation. Most days you'll see only the swap history — clean swaps no longer pause for review. Filter to Accepted to see the swaps that need a supervisor decision (compliance was flagged).

1. Use the status filter to find Accepted swaps.
2. Click a swap request to see the details of both shifts, both employees, and the violation list that blocked auto-approve.
3. Review the information and click Approve (override) or Reject.

Compliance Checks

When Employee B clicks Accept, the system simulates both employees with their swapped shifts and checks for violations:

• Shift overlap — if the post-swap assignment would put either employee at two places at once, the swap fails fast with HTTP 422 and the swap stays in Pending. Overlap is constraint-enforced at the database, so it cannot be overridden by anyone — the system surfaces the error to the requester immediately rather than wasting a manager review cycle.
• Rest period requirements between shifts
• Overtime limits for the equalization period
• Other TES compliance rules

If no violations are found, the swap auto-approves and both shifts are reassigned in a single transaction. If a non-overlap violation is detected, the swap is held at Accepted status and a notification with the violation list is sent to managers — they can either override and approve manually, or reject.

Locked Payroll Periods Block Reassignment

When a payroll period is Locked or Exported, the system refuses to perform any swap reassignment whose shift falls in that period — the period is the official record sent to payroll, and reassigning hours after lock would corrupt the books. The block applies to:

• Swap auto-approve at acceptance time
• Supervisor override approve

In both cases the API returns 409 with code: 'period_locked' and the locked period's date range. The swap stays in its current status. There is no role-level override; the only path forward is to unlock the period via the normal payroll workflow before approving.

Cascading Cancellation on Shift Mutations

If you cancel a shift, delete a draft, or change a shift's planned start, planned end, location, or assigned employee, every non-terminal swap that points at it is automatically cancelled with reason shift_changed. Both involved employees receive a "Swap auto-cancelled — the shift changed" notification and the swap row carries the same note in the UI.

The cascade fires inside the same transaction as the shift mutation, so a partial state never becomes visible. Edits to non-schedule fields (notes, training flag, etc.) do not trigger the cascade.

Reviewing on the Shift Swaps Page

The /shift-swaps page has two top-level tabs:

• Swaps (default) — bilateral exchanges, scoped to the caller's role: employees see their own; supervisors see swaps at their assigned locations; managers and CompanyAdmins see tenant-wide.
• Active Offers — open shift offers (the unilateral handoff flow). Same role-scoping rules.

The Active Offers tab can be deep-linked via ?view=offers, which is what the ShiftOfferCreated notification does so a recipient lands directly on the claim list.

Rejecting a Swap

Supervisors can reject a swap at either the Pending or Accepted stage. Both employees are notified of the rejection.

Notifications

Employees receive notifications at each stage of the swap process:

• Employee B is notified when a swap is requested.
• Both employees are notified when the swap is approved — auto-approved at acceptance, or manually approved by a supervisor.
• When compliance fails, managers receive a "swap pending approval" notification with the violation list.
• Both employees are notified when the supervisor rejects.