Skip to content

Locations and Terminals

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.

A location is a physical store: address, receipt branding, payment methods, tax zone, MSI source. A terminal is one register at a location (location_id), paired with one device through activation. The REST terminal answers do not carry the device identifier or the activation code. Merchants manage both in the Magento admin; the routes below serve the device and external integrations.

Method Route ACL Purpose
GET /V1/pos/locations Hyva_Pos::locations List locations (searchCriteria)
GET /V1/pos/locations/:locationId · /code/:code Hyva_Pos::locations Fetch by id or code
POST / PUT /V1/pos/locations · /:locationId Hyva_Pos::locations_manage Create / update
DELETE /V1/pos/locations/:locationId Hyva_Pos::locations_manage Delete
GET /V1/pos/terminals · /:terminalId Hyva_Pos::locations List (searchCriteria) and fetch terminals
POST / PUT /V1/pos/terminals · /:terminalId Hyva_Pos::locations_manage Create / update
DELETE /V1/pos/terminals/:terminalId Hyva_Pos::locations_manage Delete
POST /V1/pos/terminals/activate Hyva_Pos::locations_manage Bind a device with a one-time activation code
POST /V1/pos/terminals/deactivate Hyva_Pos::locations Release the device binding
POST /V1/pos/terminals/:terminalId/heartbeat Hyva_Pos::locations Periodic device check-in
POST /V1/pos/terminals/:terminalId/license/refresh Hyva_Pos::locations Force a license refresh from hyva.io

Locations

The device lists locations during setup (GET /V1/pos/locations?searchCriteria[pageSize]=100) and receives its own location inside the terminal config payload. Create and update take the entity wrapped in a location key; the response is the saved row. Field names are the hyva_pos_location columns. The most commonly set ones:

{
  "location": {
    "name": "Amsterdam Flagship",
    "code": "ams-01",
    "street": "Main Street 1",
    "city": "Amsterdam",
    "postcode": "1234AB",
    "country_id": "NL",
    "phone": "+31 20 123 4567",
    "vat_number": "NL123456789B01",
    "website_id": 1,
    "source_code": "ams_store",
    "is_active": true,
    "payment_methods": "cash,card",
    "low_stock_threshold": 5,
    "tax_use_address": true,
    "receipt_header": "Thank you!",
    "receipt_footer": "",
    "card_payment_provider": "mollie",
    "pickup_completed_status_code": "complete",
    "layaway_deposit_min_percent": 25,
    "layaway_expiry_days": 30,
    "layaway_cancellation_fee_percent": 0
  }
}

Nullable override fields (vat_number, receipt_logo_size, card_payment_provider, receipt_store_info_placement, and others) inherit the global default when null. Errors: 404 for unknown id or code, 400 (CouldNotSaveException / CouldNotDeleteException) on failed writes.

Terminals

Standard CRUD. Create and update take the entity wrapped in a terminal key:

{
  "terminal": {
    "name": "Front Desk",
    "location_id": 1,
    "is_active": true
  }
}

A terminal is paired with a device only through activation. GET /V1/pos/terminals, GET /V1/pos/terminals/:terminalId and the save answers carry neither device_identifier nor activation_code, and a POST or PUT body that sets either is refused with 400 as an unsupported field. Filtering the list on device_identifier still works. A terminal row created in the admin carries a generated one-time activation code, shown in the admin grid, and a null activation_used_at.

Activation Flow

  1. An admin creates the terminal in Hyvä POS > Store Setup > Terminals; the grid shows the generated activation code.
  2. The cashier enters the code on the device during setup. The app calls:
POST /V1/pos/terminals/activate
{ "activationCode": "K7Q2M9", "deviceIdentifier": "8F3A61E2-5B2D-4C55-9A1E-0F47C2D9B3A1" }
  1. The server matches the code against terminals with an unused code, stamps activation_used_at (codes are single-use), binds the device_identifier, and, when a license is linked and hyva.io credentials are configured, activates the license upstream. A license already bound to another device is auto-released and retried once.
  2. The response carries everything the register needs to boot: the terminal, its location, the staff who may sign in, their roles, and fiskaly_credentials, reserved for fiscal signing in Germany and Austria, where Hyvä POS is not yet available:
{
  "terminal": { "terminal_id": 3, "name": "Front Desk", "location_id": 1, "is_active": true, "activation_used_at": "2026-08-12 09:14:02" },
  "location": { "location_id": 1, "name": "Amsterdam Flagship", "code": "ams-01" },
  "staff_list": [ { "staff_id": 7, "first_name": "Anna", "last_name": "de Vries", "email": "anna@example.com", "role_id": 2, "is_active": true } ],
  "role_list": [ { "role_id": 2, "name": "Cashier", "permissions": "{\"place_orders\":true}", "is_active": true } ],
  "fiskaly_credentials": null
}
  1. The device follows up with GET /V1/pos/terminals/:terminalId/config for the resolved config and license detail, and starts heartbeating.

Errors: 400 Invalid activation code format. (code must match ^[A-Za-z0-9]{4,12}$) or Invalid device identifier format. (^[a-zA-Z0-9-]{1,100}$); 404 Activation code not valid. for unknown or already-used codes (attempts are rate limited per device identifier); 400 This terminal is disabled. Enable it in the Magento admin before activating. when an admin has switched is_active off; 400 with parameters.outcome activation_refused when hyva.io refuses the license, with the reason_code hyva.io gave when it gave one; the message is hyva.io's sentence. When hyva.io gives no answer at all, reason_code is unreachable and the message reads Couldn't reach hyva.io to check the license. Check the store's connection and try again.

Deactivation (POST /V1/pos/terminals/deactivate)

Called by the device when the user unregisters the terminal in Settings. Body: { "terminalId": 3, "deviceIdentifier": "8F3A61E2-..." }. The server verifies the device identifier matches the registered one, then releases the binding. Returns true. Errors: 404 unknown terminal, 401 (AuthenticationException) on device mismatch.

Heartbeat (POST /V1/pos/terminals/:terminalId/heartbeat)

The device's periodic check-in. It updates last_seen_at, verifies the device, stores the register session the device reports, and returns terminal, config and license state in one call.

{
  "deviceIdentifier": "8F3A61E2-...",
  "openRegister": {
    "open": true,
    "heartbeat_interval": 900,
    "session_id": "4C1D9E2A-6B7F-4E3A-9C55-1A2B3C4D5E6F",
    "opened_at": "2026-10-20T07:12:04Z",
    "business_date": "2026-10-20",
    "timezone": "Europe/Amsterdam",
    "opened_by": { "staff_id": 7, "name": "Veronica Costello" },
    "document_count": 14,
    "sales_total": "1290.50",
    "currency": "EUR"
  }
}

openRegister is optional. Send {"open": false, "heartbeat_interval": 900} when no session is open. sales_total is a decimal string in major units, and heartbeat_interval is in seconds. The module stores it per terminal in hyva_pos_terminal_session; every heartbeat that identifies its device and carries it overwrites the row, and a heartbeat without it leaves the stored state as it is. An open session is a live view and never becomes a closing; the closing is the register report the register uploads when it closes.

{
  "is_active": true,
  "device_identifier": "8F3A61E2-...",
  "require_terminal_registration": true,
  "config_hash": "…",
  "staff_hash": "…",
  "hyvaio_connection_ok": true,
  "has_license": true,
  "license_status": "active",
  "license_expires_at": "2027-08-12 09:14:02",
  "license_token": "eyJhbGciOi...",
  "inactive_reason": null,
  "last_upstream_check_at": "2026-08-12 06:00:11",
  "last_upstream_check_succeeded": true
}
  • device_identifier is returned only to the paired device. A call without deviceIdentifier gets the rest of the answer and an empty device_identifier.
  • config_hash covers the location row, every stored POS and tax setting, and the staff and roles the terminal config ships for the location: each active staff member assigned to the location or to all locations (ID, updated_at, passcode_updated_at, is_active, role_id, all_locations) and each role they hold (ID, name, permissions, is_active, updated_at). A new passcode, a role change, or a staff member added to or removed from the location moves it; a change to staff of another location does not. Pull the terminal config again when it moves.
  • staff_hash is the staff and roles part of config_hash on its own, and null when the terminal has no location. Compare it between heartbeats: unchanged, the staff you hold still match the store.
  • An inactive terminal's answer carries neither hash.
  • inactive_reason explains is_active: false: code_regenerated, license_revoked, or deactivated (null while active), so the lock screen shows the right message.
  • last_upstream_check_at / last_upstream_check_succeeded describe the most recent hyva.io refresh; the device does not contact hyva.io itself.

The terminal config returns the stored session to the paired device as open_register:

Field Content
status open or closed as the last report stated; unknown when heartbeats arrive but none carried a session report within three heartbeat intervals (a register from before the field); not_reporting when no heartbeat arrived within three heartbeat intervals. A register that gives no interval counts 900 seconds per interval
reported_at When the stored report arrived, UTC
session The open session's facts (session_id, opened_at, business_date, timezone, opened_by, document_count, sales_total, currency); null unless the stored session is open

Errors: 404 unknown terminal, 401 on device-identifier mismatch.

License Refresh (POST /V1/pos/terminals/:terminalId/license/refresh)

Triggered by the "Check License" button on the device; forces an immediate refresh against hyva.io instead of waiting for the scheduled check. Body: { "deviceIdentifier": "8F3A61E2-..." }.

{
  "success": true,
  "license_token": "eyJhbGciOi...",
  "license_status": "active",
  "license_expires_at": "2027-08-12 09:14:02",
  "fiskaly_credentials": null,
  "error": null
}

On upstream failure, success is false and error carries the hyva.io message. Errors: 404 unknown terminal, 401 on device-identifier mismatch. A paired terminal refuses an empty deviceIdentifier with Device mismatch., as it refuses a wrong one.