Skip to content

Installing the Module

Hyvä POS is in closed beta

Hyvä POS is currently in a closed beta (pilot phase) with a small group of merchants. It is not yet generally available: the App Store release follows the pilot, and features and configuration may still change - possibly in backwards-incompatible ways - before the general release. Want to take part? Sign up at hyva.io/pos.

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

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

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). Agencies can write bridges for other vendors.

Updating

Module updates are ordinary Composer updates. An app update never hard-blocks on the module version: a newer app detects what the installed module supports and keeps working, with newer features staying dormant until the module catches up. The installed module version is visible in the app's connection status page.

The app itself is not extensible

Customization happens on the Magento side, where you can extend everything the way you are used to. The app is intentionally a fixed, tested surface; the module and its bridge contracts are the extension points.