Audit and Telemetry
Hyvä POS is on the App Store
The free app is out for iPhone, iPad and Mac: install it from the App Store, connect your Magento store and sell. PRO, the Magento module with a license per terminal, follows shortly. News and pricing are at hyva.io/pos.
Three independent trails. The audit log records who changed what: one row per field change, written when a cashier edits data from the device (and by admin-side saves of POS entities). Sale events record approvals and interventions at the register and link them to the sale's order. Telemetry records operational events for diagnostics and usage reporting.
| Method | Route | Purpose | ACL |
|---|---|---|---|
POST |
/V1/pos/audit-log |
Submit field-change entries from a terminal | Hyva_Pos::locations |
GET |
/V1/pos/audit-log |
List audit entries via searchCriteria |
Hyva_Pos::pos |
POST |
/V1/pos/telemetry |
Submit an event batch from a terminal | Hyva_Pos::locations |
GET |
/V1/pos/telemetry/report |
Export an aggregated report | Hyva_Pos::pos |
POST |
/V1/pos/sale-events |
Store a batch of sale events | Hyva_Pos::locations |
GET |
/V1/pos/sale-events |
List stored sale events via searchCriteria |
Hyva_Pos::locations |
The audit log and telemetry GET routes carry the admin-level Hyva_Pos::pos resource, so a terminal-scoped integration token can write but not read them; reading those trails is an admin/reporting concern. GET /V1/pos/sale-events carries Hyva_Pos::locations.
Submit Audit Entries
POST /V1/pos/audit-log
Called by the app after on-device edits: a stock correction, a product price change, a customer edit. The body is a batch of entries; each entry is one field change:
{
"entries": [
{
"entity_type": "stock",
"entity_id": 2043,
"entity_name": "Classic Shirt (WSH12)",
"field_name": "qty",
"old_value": "14",
"new_value": "12",
"change_source": "pos_terminal",
"staff_id": 7,
"staff_name": "Anna",
"terminal_id": 3,
"terminal_name": "Front Desk 01",
"location_id": 1,
"location_name": "Amsterdam Store"
}
]
}
Returns true. Field notes:
entity_type,entity_id, andfield_nameare required; an emptyentity_typeorfield_nameis stored as"unknown"rather than rejected.change_sourcedefaults topos_terminalwhen omitted. The column also carriesadminandapifor rows written server-side.- The
*_namefields are denormalized: they capture the display names at the time of the change, so the trail stays readable after a staff member, terminal, or location is renamed or deleted. old_value/new_valueare free-form strings; the app sends whatever representation the edited field had.
The module also writes a row for every held-cart recall (entity_type held_cart), identifying the staff member and the location.
List Audit Entries
GET /V1/pos/audit-log?searchCriteria[filter_groups][0][filters][0][field]=entity_type&searchCriteria[filter_groups][0][filters][0][value]=stock
Standard Magento searchCriteria listing over the hyva_pos_audit_log table, returning the usual items / search_criteria / total_count envelope. Each item carries the submitted fields plus the server-assigned log_id and created_at timestamp. Useful filter fields: entity_type, entity_id, change_source, staff_id, terminal_id, location_id, created_at.
This is the same data behind the admin grid; admin-side saves of POS entities (for example location edits) land in the same table with change_source set to admin and the admin user's name recorded.
Retention
Audit rows are never purged automatically; there is no cleanup cron for hyva_pos_audit_log. The audit trail is kept as the compliance record; pruning the table is a manual database action.
Sale Events
A sale event is an approval or an intervention at the register: a manager approving a discount for a cashier, a staff member removing an item at a self-checkout. Magento stores one row per event_id in hyva_pos_sale_event.
Submit Sale Events
POST /V1/pos/sale-events
{
"events": [
{
"event_id": "0B6E3F8A-2C1D-4E5F-9A7B-3C4D5E6F7A8B",
"kind": "approval",
"action": "cart_discount",
"basket_id": "9F3C2A1B-7D4E-4A61-8C0B-2E5F1A9D3C77",
"sale_id": "9A9E4AF3-0E4E-4B2A-9D3E-1C2B3D4E5F60",
"terminal_id": 3,
"location_id": 1,
"requested_by": { "staff_id": 12, "name": "John Cashier" },
"approved_by": { "staff_id": 3, "name": "Jane Manager" },
"subject": null,
"amount": "10.00",
"detail": null,
"occurred_at": "2026-10-20T09:41:07Z"
}
]
}
| Field | Type | Rule |
|---|---|---|
event_id |
string | Required. A UUID |
kind |
string | Required. approval or intervention |
action |
string | Required. What was approved or done, at most 64 characters (line_discount, cart_discount, price_override, refund_discrepancy_writeoff, resolve_due_payment, ...) |
basket_id |
string | Required. The register's basket, at most 64 characters |
sale_id |
string or null | The sale's ID once the basket became a sale, at most 64 characters |
terminal_id, location_id |
int or null | |
requested_by |
object | Required. staff_id (int or null), name (string or null) |
approved_by |
object or null | staff_id, name |
subject |
string or null | What the event applies to, such as a line; cut to 255 characters |
amount |
decimal string or null | The amount approved |
detail |
string or null | Free text; cut to 4000 characters |
occurred_at |
string | Required. ISO 8601 with a time zone; stored in UTC |
The answer lists each event under accepted (stored by this request), duplicates (stored already) or rejected (with the reason; the rest of the batch is stored). Resend a batch after a lost answer.
Order Linking
An event with a sale_id is linked to the order whose pos_sale_id matches: at once when the order exists, otherwise when the order is saved, after its transaction commits. The event row takes the order's order_id, and the order's history gets a comment that is not visible to the customer, for example Cart discount approved by Jane Manager for John Cashier, 10.00. A failed link is logged and never fails the order save; the event stays stored and is linked by the order's next save or a resend.
List Sale Events
GET /V1/pos/sale-events takes standard searchCriteria and returns the items / search_criteria / total_count envelope.
Submit Telemetry
POST /V1/pos/telemetry
Batch upload of operational events. The payload is a free-shape object with device context at the top level and an events array:
{
"payload": {
"location_id": 1,
"terminal_id": 3,
"device_id": "8F1C2D3E-4A5B-6C7D-8E9F-0A1B2C3D4E5F",
"app_version": "0.3.0",
"events": [
{
"event_type": "counter",
"event_name": "checkout_completed",
"event_data": {"payment_method": "cash"},
"value": 1,
"period": "2026-08-12",
"recorded_at": "2026-08-12 14:03:22"
}
]
}
}
event_type and event_name are required per event; event_data (arbitrary JSON), value (numeric), period, and recorded_at are optional. The endpoint is lenient: a non-array payload or an empty events array returns false instead of an error, and individual malformed events are skipped while the rest of the batch is stored. There is no validation failure path, so a telemetry problem cannot stop a terminal.
Telemetry Report
GET /V1/pos/telemetry/report?locationId=1&from=2026-08-01&to=2026-08-12
Admin-side export of aggregated telemetry for the optional location and date range. All three query parameters are optional.
Retention
A daily cron (hyva_pos_telemetry_cleanup, 04:00 server time) aggregates raw events into daily summaries and then purges: raw events and summaries older than hyva_pos_advanced/telemetry/retention_days (default 90) are deleted. Telemetry is a rolling diagnostic window; anything that must be retained belongs in the audit log or on the order.