What's New in POSVelo v2
HRM, Payroll, Employee Self-Service, and real-time notifications — added on top of the v1 POS you already know
POSVelo v1 is a Point-of-Sale system: products, inventory, sales, customers, reports. v2 keeps every bit of that unchanged and adds a complete staff-management layer: hiring records, attendance clock-in/out, shift rosters, leave, payroll, payslips, a self-service portal for employees, and a live notification bell. Nothing from v1 was removed — v2 is purely additive.
This page covers the v2 foundation. The latest release, v2.1, adds Stripe subscriptions & billing, a Super Admin platform console, loyalty point redemption, multi-day leave & holidays, and per-account workspace preferences — see What's New in v2.1.
The Three Big Additions
| Area | What it is, in one sentence | Who uses it |
|---|---|---|
| HRM & Payroll | Manage employees, departments, attendance, shifts, leave, holidays, salary structures, and run payroll that produces payslips. | Owners, Admins, HR Managers, Accountants, Store Managers |
| Employee Self-Service (ESS) | A simple personal portal where each staff member sees only their own attendance, roster, leave balance, and payslips — and can clock in, apply for leave, or swap a shift. | Every employee (cashiers, staff, managers — anyone with a login linked to an employee record) |
| Real-Time Notifications | A live bell icon that pings instantly (over WebSockets) when something needs attention — e.g. a new leave request, or a low-stock alert. | Everyone — each person sees only their own notifications |
How v1 and v2 Live Side by Side
POSVelo uses URL versioning. The web address (path) of every API request tells the server which version's rules to apply.
| Path prefix | What it serves | Example |
|---|---|---|
/api/v1/... | The original POS endpoints. Still live and unchanged. | /api/v1/products |
/api/v2/... | The new HRM, ESS, Payroll, Brands, geofencing, HR analytics, and notification endpoints. | /api/v2/hr/employees |
The two versions are not separate apps. The same backend server (port
5000) and the same frontend (port 3000) serve both.
A cashier ringing up a sale (v1) and an HR manager running payroll (v2) are
using one running system. There is nothing extra to install for v2 — it is
the same two repositories described in
Introduction & Overview.
New & Expanded Roles
v2 expands the role list from 4 to 7. The original four are unchanged; three new ones were added for staff management.
| Role | Status | What they do in v2 |
|---|---|---|
| SUPER_ADMIN | v1 | Platform-wide admin across all tenants. |
| ADMIN | v1 | Full control of one business, including all of HRM & Payroll. |
| MANAGER | v1 | Store-level. In v2 also approves their team's attendance corrections, leave, and shift swaps. |
| CASHIER | v1 | POS terminal. In v2 also gets a personal ESS portal (own attendance, leave, payslips). |
| HR_MANAGER new in v2 | v2 | Runs the HR domain — employees, attendance, shifts, leave, payroll — without POS/finance admin rights. |
| ACCOUNTANT new in v2 | v2 | Payroll-focused: create/process/disburse runs (kept separate from the person who approves them). |
| EMPLOYEE new in v2 | v2 | Self-service only. Has the ess.* permissions and nothing else — no back-office access. |
v1 uses colon-style permission strings like product:read. v2
introduces dot-style strings like hr.employees.read and
ess.leave.request.create. Both formats are checked the same way;
v1 strings keep working. The backend is always the source of truth — the
frontend only hides buttons you can't use (a convenience, not a security
boundary).
Turning HRM On for a Business (Tenant)
The HR & Payroll module is gated per tenant. If it is not enabled, every
/api/v2/hr/* and /api/v2/me/* endpoint returns a
"module disabled" response instead of data. This lets a plain POS customer run
without HR clutter, while an HR customer turns it on.
Sign in as an Admin
Only the ADMIN role can change which modules are enabled for
the business.
Open tenant settings
The HR configuration lives under the tenant's settings (the
settings.hr section — see the
v2 API Reference). It holds the default
country preset, fiscal-year start, payroll cycle, work-week days, and the
attendance grace period.
Enable the HR module flag
With HR enabled, the HRM menu group and the /me self-service
portal become available to users who hold the matching permissions.
A Sensible First-Run Order
HRM data has dependencies — you can't assign a salary before a salary structure exists, and you can't roster a shift before a shift template exists. This order avoids dead-ends:
Org structure
Create Departments and Designations (job titles). See HRM — Org & Employees.
Employees
Add Employees. Optionally provision a login user at the same time so the person can use ESS.
Time & attendance
Define Shift Templates, publish a roster, and let staff clock in/out. See Attendance & Shifts.
Leave & holidays
Create Leave Types and Policies, import a holiday preset, and open leave applications. See Leave & Holidays.
Payroll
Build a Salary Structure (or apply a country preset), assign salaries, then create, process, approve, and disburse a Payroll Run. See Payroll.
Self-service & notifications
Employees use the ESS portal; approvers get live notifications as requests arrive.
Try the API in 5 Minutes (Postman)
The backend ships a Postman collection that covers all of v1 and v2. It is the fastest way to see real requests and responses without touching code.
| File (in the backend repo, under /postman) | Purpose |
|---|---|
POSVelo-API.postman_collection.json | The full v1 + v2 request collection, grouped by module and version. |
POSVelo-Development.postman_environment.json | Variables like base_url, access_token, and chained IDs (employee_id, brand_id, …). |
postman/README.md | Import & usage notes. |
Import both files
In Postman, import the collection and the environment, then select the POSVelo - Development environment (top-right).
Log in
Run Auth › Login. The test script automatically saves your
access_token and refresh_token into the
environment — every protected request reuses them.
Pick a store
Run Stores › List Stores — the first store's id is saved as
store_id for later requests.
Walk the HR folder
Create a department, a designation, then an employee — each "create" saves
its returned id (e.g. employee_id) so the next request can
chain off it.
Default base URL is {{base_url}} = http://localhost:5000.
Auth is a Bearer JWT: the access token lasts 15 minutes, the
refresh token 7 days. Use Auth › Refresh Token
to rotate — refresh tokens are single-use (theft protection).
Where to Go Next
| If you want to… | Read |
|---|---|
| Add staff and set up your org chart | HRM — Org & Employees |
| Track time, run rosters, handle swaps | Attendance & Shifts |
| Set up leave types and approvals | Leave & Holidays |
| Run payroll and issue payslips | Payroll |
| Give employees a personal portal | Employee Self-Service |
| Understand the live bell + WebSockets | Real-Time Notifications |
| See every v2 endpoint, request & response | v2 API Reference |