Expense claims

An expense claim is one purchase: the day the money was spent, what it was spent on, how much and in which currency, and — nearly always — a photograph of the receipt. One claim, one receipt, one decision. A month of taxis is a month of claims, not one claim for the month, because an approver approves a thing that happened.

A reimbursement is not pay. It is the company giving back money that was already the employee's. That distinction is not a nicety — it decides the tax treatment, the pension base and the overtime base, all of which the shipped REIMBURSEMENT component gets right by default (see how the money comes back).

The register lives at Payroll & pay adjustments → Expense claims. Staff file their own from the portal's Expenses tab; HR and managers can file on somebody's behalf. Everything past that point is the same for both.

From the portal. The employee opens Expenses → New claim, picks the day and the category, types the amount, and attaches the receipt — a phone photograph is the expected case. The claim is created Pending and goes straight to its approver.

On somebody's behalf. Anyone with expenses.manage uses File a claim on the register, which asks for the staff number as well. Same row, same route, same decision — filing for somebody is not approving for them.

Receipts accept the usual document types (PDF, Word, JPG, PNG, WebP, HEIC) up to 50 MB, the same rules the rest of HumanR applies to uploads. They are stored outside the web root under generated names with a SHA-256 of the bytes, and they are only ever served back through a permission check — a receipt is never a public URL. More can be attached to a claim while it is still awaiting a decision.

A claim can be filed for a spend from months ago. Unlike an overtime claim, it does not have to fall inside an open payroll period: a reimbursement is not pay for the day it names, so a late claim simply rides the next run. What is refused is a date in the future, a date before the employee joined, and an amount of zero or less.

Every claim is filed under a category — as shipped: TRAVEL, MEALS, MEDICAL, PHONE, OTHER. Edit the list from Categories on the register (needs expenses.manage): change the names, add your own, and give any of them a per-claim cap.

A cap blocks the submission rather than warning about it, on both the portal form and the register's, with a message naming the cap. It is compared against the figure as claimed and deliberately not converted between currencies: a cap is a spending limit somebody typed ("no single meal over 500"), and running it through a payroll exchange rate would make the same lunch pass or fail on a rate nobody set for that purpose.

Deactivate rather than delete. A category that is switched off stops accepting new claims but keeps every claim already filed under it — the history stays readable and reportable, because claims store the category's code, not a row that could be removed underneath them.

Claims ride the ordinary approval engine, banded on the amount — expense routes are money routes, so a route that reads "up to 1,000 the department head, above that the GM" works from day one. The approver sees the category, the description and the receipts inline on the approval page, so evidence does not mean opening another screen.

Approving flips the claim to Approved, which is what payroll reads. Rejecting marks it Rejected and keeps it: a refused claim is part of the paper trail, and the same receipt can be refiled with a corrected figure. Every decision fires the usual approval.expense-claim.approved / .rejected webhook, so a finance channel can be told without anybody watching the register.

Withdrawing. While a claim is still pending, the employee can withdraw their own from the portal and HR can delete it from the register. Both remove the row and its receipts — a withdrawn claim is one that was never made. A decided claim never deletes: approved money may already be stamped onto a run, and a rejection is the evidence that it was refused.

When a payroll run is generated, it picks up every approved claim that has not been repaid yet and whose spend date falls on or before the end of the period. Each employee's claims are added together into one REIMBURSEMENT line on the payslip — one line however many claims, the same rule overtime follows — and each claim is stamped with that run.

Regenerating a draft run releases those stamps and folds them again, so nothing is repaid twice and an amended claim is picked up. A claim approved after a run has been finalized is not stranded: it stays unstamped and the next run repays it. The register's header, the Settled to a run field and the portal's money card all answer the same question from different sides — what is approved and still waiting.

Currency. Money is repaid in the currency it was spent in. If an employee has no salary package in that currency, the run gives them a line in that currency carrying the reimbursement alone, rather than repaying rufiyaa against a dollar receipt. Nothing is converted anywhere in this module.

The portal's Expenses tab is the employee's own list and nothing else: their claims, their statuses, their receipts. At the top, what has been approved and is waiting for the next run — the answer to "when do I get my money", which is otherwise a message to HR.

They can file, attach, download their own receipts, and withdraw anything still pending. They cannot see another person's claim, and the approver's route is not shown to them — the state they get is the status badge and, where a request is open, the approval it is waiting on through My requests.

The register carries the standard filter box, so it answers questions rather than just listing rows:

• status:Pending — what is waiting on a decision.
• status:Approved settled:no — approved money the next run will repay.
• cat:TRAVEL amount:>=500 date:>=-30d — the last month's larger travel claims.
• dept:"Front Office" -status:Rejected — one department, refusals excluded.

The same fields are a source in the report builder — group by category to see which ones run hot, by department to see where the budget goes, by month to see the trend — and claims are indexed for the topbar search, by staff number, name and description. Receipt filenames are deliberately not indexed: people name photographs carelessly, and a receipt should be found through its claim.

• expenses.view — see the register, claim pages, receipts and the report source.
• expenses.manage — file on somebody's behalf, attach receipts, delete a pending claim, and edit the category catalogue.
• Deciding a claim is approvals.act on its routed step, not an expense permission — so a manager who may file for their team does not thereby approve for them.
• Downloading a receipt is recorded as a sensitive view, the same treatment employee documents get.
• The category catalogue is instance configuration, not demo data: reseeding a demo database leaves your edited categories alone.
• The whole module is dark until Features:EnableExpenses is turned on for the instance — both screens answer 404, nothing is indexed, and payroll picks nothing up. Turning it on shows the module; granting the permissions and building a route opens it.