Upgrading
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.
Upgrade notes for each module release that asks something of you are below, newest last.
Two principles hold across every upgrade:
- Selling never waits on the module. Selling and the free features run on Magento's standard REST API, whatever module version the store has. Below module 1.1.0 the PRO features stay off, and a feature that needs a later module version stays off until the store has that version; in both cases the register shows a notice with the version needed. The installed module version shows in the app's connection status page.
- App updates come through the App Store and module updates through Composer. An app update never needs a module update. From module 1.5.0, update the app first and the module after it: that module refuses refunds to the original payment and to store credit from an older app; see Update the App With the Module.
Module 1.4.0
Module 1.4.0 stores register closings in Magento. Register 0.3.0 sends them to a module from 1.4.0; on an older module it keeps them on the device and lists one entry under Reports → Sync Issues, "Closings are kept on this device", which shows the module version that takes them. Closings issued before the update upload once the store runs 1.4.0.
setup:upgrade adds the Upload Register Reports permission to every admin role and integration that may upload receipts, so existing registers keep their access. Admin users see Hyvä POS → Reports when their role has Register Reports; adding annotations takes Annotate Register Reports. Roles with all resources have both.
Module 1.4.0 makes no change to the bridge contract: the bridges released for 1.3.0 run unchanged.
Module 1.3.0
Module 1.3.0 changes the contract the bridge modules implement, in place. It needs the matching bridge releases:
| Bridge | Version for module 1.3.0 |
|---|---|
| Amasty | 0.3.0 |
| Adobe Commerce | 0.3.0 |
| Aheadworks | 0.2.0 |
| Mirasvit | 0.2.0 |
A bridge built for module 1.2.0 does not implement the 1.3.0 contract. Update the module and the bridges you run together.
Module 1.4.1
Module 1.4.1 stores the comments the register sends with a sale: the receipt comment on the synced receipt, and a line comment on the synced receipt line and on the Magento order item, as an option named Comment. The register sends them once the module reports the capability; on an older module it prints them and writes the comment-history lines as before, and leaves the receipt record and the order item without them. See Comments and Notes.
Module 1.5.0
Update the module, run the setup upgrade and recompile:
composer update hyva-themes/magento2-hyva-pos
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush
Database Changes
setup:upgrade adds five tables and these columns:
| Table | Holds |
|---|---|
hyva_pos_terminal_session |
The register session each terminal last reported with its heartbeat |
hyva_pos_register_report_provider |
The card collected and refunded per payment provider for each register closing |
hyva_pos_sale_event |
Approvals and interventions at the register, linked to the sale's order |
hyva_pos_refund_approval |
Managers' approvals of refund payouts (the token's hash, never the token) |
hyva_pos_refund_operation |
Every refund operation the store authorized, so each one runs once |
| Column | Holds |
|---|---|
hyva_pos_register_report.reconciliation_json |
What the check of a closing against Magento's orders and credit memos found |
hyva_pos_receipt_item.comment |
The cashier's comment on a receipt line |
hyva_pos_fiscal_export.started_at, worker_token |
Which run of the fiscal export holds an export row |
sales_order.pos_after_save |
The steps a register order ran once it was committed |
Its data patches:
CopyRegisterReportProviderscopies the card provider totals of the closings you already have into the new provider table.MarkPlacedOrdersAfterSaveStepsmarks the register orders placed before the update as having run their after-save steps, so no historical coupon is counted twice.EncryptFiskalyCredentialsencrypts the stored fiskaly credentials.GrantTerminalAclToLocationRolesgives each admin role that allows Locations the matching Terminals permissions once. Integration roles are left as they are.
No admin role permission is new, and no setting needs to be filled in.
Update the App With the Module
This module checks every refund a register makes, and it refuses some refunds from a register older than app 0.4.0. Update the app on every device first, then the module.
Between the two updates, refunds work as follows:
| Refund | App 0.4.0 on an older module | Older app on this module |
|---|---|---|
| Refund to the original payment | Works as before | Refused until the app is updated |
| Refund to store credit | Works as before | Refused until the app is updated |
| Cash refund at the register | Works as before | Works as before |
| Card refund through a payment terminal, or recorded as a manual card refund | Works as before | Works as before |
| Exchange | Works as before | Works as before |
| Return kept for a later payout at the register | Works as before | Works as before |
| Layaway cancellation that refunds the deposit | Works as before | Works as before |
App 0.4.0 reads which refund checks the store's module offers. An older module offers none, so the app refunds as before and the register's own approvals decide; a manager's refund approval notes that the store does not check it yet. Nothing is refused.
When the module is updated first, refunds to the original payment and to store credit stop on every register that still runs an older app, and that register shows "Update the register to refund from it." Nothing is refunded or booked for a refused refund. These refunds work again once that register's app is updated. Sales, cash, card and exchange refunds, and layaway cancellations keep working throughout.
Before you update the module, let every register send the refunds it still holds, so Reports → Sync Issues lists none. A refund that a register on app 0.4.0 paid out at the counter while the store ran the older module, and had not yet sent to Magento, is not booked by this module.
Once a register has connected to this module, it keeps the module's refund checks, also when the store goes back to an older module. On that older module, the register cannot pay refunds out at the counter.
Run Cron for Every Group
The license refresh, the fiscal export and the new hourly check of register closings (hyva_pos_reconcile_register_reports, at 40 minutes past the hour) run in their own cron group, hyva_pos_remote, in a separate process, so a slow answer from hyva.io does not hold up the five-minute jobs of the default group. A server that runs bin/magento cron:run without --group runs it. A server that runs selected groups only adds --group=hyva_pos_remote; without it, licenses stop renewing and closings stay at Waiting for check.
Translations
Admin, cashier and API messages use American English (canceled, license, organization, behavior), and a register closing check that has not run reads "Waiting for check" instead of "Not checked". A store translation keyed on an earlier phrase needs its key updated; i18n/en_US.csv carries the new source strings.
What Changes for Staff
With this module, staff and role changes reach the registers at their next heartbeat instead of at the next app start, and a staff member removed from a location is signed out of its registers. With app 0.4.0, discounts and price changes follow the role's Apply Discounts and Price Override permissions, which the default Cashier role does not have; a cashier asks a manager to approve them. Paying a refund out follows Issue Refunds, separate from Approve Returns. Review your roles before the update if your cashiers give discounts or refunds on their own.
Offline Sign-In After the Update
App 0.4.0 dates each PIN it caches for offline sign-in. A PIN cached by an earlier app has no date, so the first start of app 0.4.0 removes it. While the register can reach the store nothing changes: the next sign-in verifies the PIN online and caches it again. Only a sign-in while the store is unreachable shows "Connect to the store and sign in once after this update." Sign in once while the register is connected before relying on offline sign-in. Sales, payments and returns waiting to be sent to Magento are kept.
Removed
POST /V1/pos/credits/refund is removed; an integration that called it refunds to store credit through the return settle. GET /V1/pos/terminals and the terminal save no longer carry device_identifier or activation_code. See the developer docs.
Dashboard Widgets
Update hyva-themes/magento2-hyva-pos-dashboard-widgets to 0.3.0 for the POS Register Closings widget. Each widget now needs its Hyvä POS resource on the admin role (Receipts, Terminals or Register Reports), so a role without it no longer sees POS revenue on the dashboard.
Module 1.6.0
Update the module, run the setup upgrade and recompile:
composer update hyva-themes/magento2-hyva-pos
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush
The Stock Packages
Module 1.6.0 requires hyva-themes/magento2-inventory-order-reservation 0.1, the open-source stock registration module, and a store with Magento Inventory needs its companion hyva-themes/magento2-inventory-order-reservation-msi as well. Both are on the public Packagist, so the update brings the first one in; require the companion on a Magento Inventory store.
Update the module and the packages together. An older module with the 0.1 packages leaves the register's source assignment before the stock placement unplugged; module 1.6.0 with the packages but without the companion leaves a Magento Inventory store's register orders owed until the companion is installed. Admin messages will warn about this. Orders placed before the update are not reserved after the fact.
Handover Shipments
The register marks the shipment that hands the goods over at the counter, from app 0.5.0 and only to a module that lists handover_shipments in its capabilities, which 1.6.0 does. On such a shipment a line the register sold past its stock check is deducted below zero as before, and a line the register saw enough stock for is deducted below zero and recorded on the order as stock drift instead of failing the shipment. Any other shipment, from the order screen, a pickup collected later or the admin, keeps Magento Inventory's refusal. A register on an older app sends no marker and ships as before.
Shipments From the Order Screen
A shipment the register creates from an order through ship-with-label is read against the source first: a line the source cannot cover is refused, with the location and the lines in the message, instead of Magento's "Could not save a shipment, see error log for details".