Installing the Module

The Hyvä POS module adds the Hyvä POS section to your Magento admin and the API the PRO features use. It installs like any Hyvä product, with Composer.

Credentials

The module is distributed through Hyvä's private Packagist repository. Your license comes with a Packagist key and a project name; find both in the license instructions on the Hyvä Hub or in your credentials email.

# Add Your Hyvä Packagist Key to Your Project's auth.json
# Replace yourLicenseAuthentificationKey with Your Actual Key
composer config --auth http-basic.hyva-themes.repo.packagist.com token yourLicenseAuthentificationKey

# Add the Hyvä Private Packagist Repository
# Replace yourProjectName with Your Project Name
composer config repositories.private-packagist composer https://hyva-themes.repo.packagist.com/yourProjectName/

If the project already runs a Hyvä product (theme, checkout), this is configured and you can skip to the install.

Install

composer require hyva-themes/magento2-hyva-pos
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

The module installs with or without the Magento Inventory (MSI) packages. With them, locations map to an inventory source and registers can read and write stock per source; without them, registers read and write Magento's plain stock figures and returns restock there.

Verify

1. Run bin/magento module:status Hyva_Pos. It must report the module as enabled.
2. Open the admin. The sidebar has a new Hyvä POS menu: Getting Started and Help, Store Setup (Locations, Licenses, Terminals, Receipts), Staff (Manage Staff, Roles) and Operations (Held Carts, Audit Log, Telemetry, Fiscal Exports).
3. Open Stores → Configuration → Hyvä POS. The General → Version panel shows the installed module version and whether an update is available.

Common Install Failures

• Could not find a matching version of package hyva-themes/magento2-hyva-pos: the private repository is not configured for this project, or your Packagist key does not include the POS product. Re-check the two composer config commands, then verify the license on the Hyvä Hub.
• HTTP 401/402/403 from hyva-themes.repo.packagist.com: wrong key, wrong project name, or an inactive subscription. The key in auth.json must match the project name in the repository URL.
• The Hyvä POS menu is missing after install: setup:upgrade did not run, or the admin caches are stale. Run bin/magento setup:upgrade && bin/magento cache:flush and reload the admin.
• The app says the module is not detected: the pos/ REST routes are not reachable. Confirm the module is enabled, then check that your web server does not block or rewrite /rest/ paths. See connection troubleshooting.

Optional Bridge Modules

If you already run a store-credit, gift-card, reward-points or RMA module from a third-party vendor, install the matching bridge so the POS uses it:

composer require hyva-themes/magento2-hyva-pos-adobe-commerce   # Adobe Commerce native features
composer require hyva-themes/magento2-hyva-pos-aheadworks
composer require hyva-themes/magento2-hyva-pos-amasty
composer require hyva-themes/magento2-hyva-pos-mirasvit

These four bridges require module ^1.3: install or update the module to 1.3.0 together with them. Each bridge translates the POS credit and RMA calls to the vendor's own APIs, so gift cards sold online through your existing module redeem at the register unchanged. After installing a bridge, pick the provider per feature under Stores → Configuration → Hyvä POS → Advanced → Credit & Return Providers (see global settings). Bridge modules lists what each bridge covers and how far along it is. Agencies can write bridges for other vendors.

Updating

Module updates are ordinary Composer updates. An app update does not require a matching module version: a newer app detects what the installed module supports and keeps working, and newer features stay inactive until the module is updated. The installed module version is visible in the app's connection status page.