Skip to content

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:

  • CopyRegisterReportProviders copies the card provider totals of the closings you already have into the new provider table.
  • MarkPlacedOrdersAfterSaveSteps marks the register orders placed before the update as having run their after-save steps, so no historical coupon is counted twice.
  • EncryptFiskalyCredentials encrypts the stored fiskaly credentials.
  • GrantTerminalAclToLocationRoles gives 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".