Skip to content

API Reference

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.

The Hyvä POS module exposes its entire surface as regular Magento web API routes under /rest/V1/pos/. The register app is another API client: activation, config sync, staff login, receipt sync, and returns all go through the routes below, and your own integrations can call the same routes. The register's refund routes also need a refund operation and a staff session or a manager's approval; see Refund Authorization.

Authentication and Authorization

Authenticate as you would against any Magento REST endpoint:

  • Bearer token: an integration access token or admin token in the Authorization: Bearer <token> header. This is what the register app uses: the access token entered during store setup.
  • OAuth 1.0a: for server-to-server integrations registered under System > Extensions > Integrations.

Every route declares an ACL resource in the module's webapi.xml. Scope a token to what it needs:

ACL resource Grants access to
Hyva_Pos::locations All read and day-to-day device calls: config, locations, terminals, heartbeat, held carts, credits, RMA and refund operations, sale events, pickups, shipping
Hyva_Pos::locations_manage Location and terminal create/update/delete, terminal activation
Hyva_Pos::staff_manage Staff reads, staff authentication, session validation, refund approvals
Hyva_Pos::staff_manage_edit Staff create/update/delete, location assignments, lockout clearing
Hyva_Pos::staff_roles / Hyva_Pos::staff_roles_manage Role reads / role create/update/delete
Hyva_Pos::receipts Receipt sync, lookups, receipt email
Hyva_Pos::register_reports_submit Register closing upload
Hyva_Pos::register_reports Register closing reads
Hyva_Pos::pos Admin-level reads: audit-log listing, telemetry report export
Hyva_Pos::register_reports_submit Uploading a register closing. Granted on upgrade to every role and integration that may upload receipts
Hyva_Pos::register_reports Reading closings: the read API, the Register Reports listing and Register Totals
Hyva_Pos::register_reports_annotate Adding an annotation to a closing in the admin
Magento_Customer::manage The pay-by-invoice credit-limit read, the newsletter routes and the customer-insights read. They reuse the core customer ACL, since they expose nothing that core customer endpoints don't already

The integration role used by a register device needs the full Hyva_Pos tree plus the standard Magento sales, catalog, and customer resources the register reads.

Conventions

  • JSON in, JSON out, standard Magento web API envelope. Errors return {"message": "...", "parameters": [...]} with HTTP 400 (validation and save errors), 401 (authentication and device-identity mismatches), 404 (entity not found), or 409 (a return or refund that cannot proceed yet, with an outcome or, for a register refund, a reason in parameters; see RMA).
  • Request bodies use the camelCase parameter names from the service interfaces (activationCode, deviceIdentifier, terminalId). Entity payloads use snake_case field names and are wrapped in a key named after the parameter: {"location": {...}}, {"staff": {...}}, {"terminal": {...}}, {"role": {...}}.
  • Three config endpoints (pos/config, pos/terminals/:terminalId/config, pos/postcode-patterns) return a JSON string: the service serializes the object, then the web API framework encodes that string again. Parse the response body, then parse the resulting string.
  • List endpoints (locations, terminals, staff, roles, receipts, register-reports) take standard Magento searchCriteria query parameters, for example GET /rest/V1/pos/staff?searchCriteria[pageSize]=200.
  • Receipt sync and order placement are keyed by the client-generated sale ID, sale events by event_id, refund operations by operation_id and register closings by report_id, so retries are safe.
  • Terminal-scoped calls (activation, deactivation, heartbeat, license refresh) carry a deviceIdentifier; the server verifies it against the registered terminal and rejects mismatches. GET /V1/pos/terminals/:terminalId/config takes the device_identifier as a query parameter and returns the license, the fiskaly credentials, the activation code and the device identifier only to the paired device.

How Config Sync and Enforcement Work

Settings flow to a device in one payload. GET /V1/pos/terminals/:terminalId/config returns the global config (everything under Stores > Configuration > Hyvä POS), the terminal's location row, the staff and roles who may sign in there, and a resolved_config that layers terminal overrides over location values over global defaults. The heartbeat response carries a config_hash over the location row, the staff and roles the payload ships, and every stored POS and tax setting. When it changes, the device pulls the full config payload again. A staff or role change reaches a register at its next heartbeat.

Configuration flows one way: a terminal does not write location settings back to Magento. A setting a cashier changes on the device stays on that device. Each lockable setting has a lock flag under Stores > Configuration > Hyvä POS > Lock Settings (hyva_pos_lock/enforcement/*); the flags travel to the device in the enforcement block of pos/config, where a locked setting takes Magento's value and its settings screen is read-only. See Configuration for the full flag list.

Routes by Area

Configuration

Method Route Purpose
GET /V1/pos/config Global POS configuration, defaults, enforcement flags
GET /V1/pos/terminals/:terminalId/config Unified per-terminal bootstrap payload
GET /V1/pos/postcode-patterns Per-country postcode validation patterns
GET /V1/pos/order-statuses Registered order statuses for picker UIs

Locations and Terminals

Method Route Purpose
GET /V1/pos/locations /:locationId /code/:code List and fetch locations
POST/PUT/DELETE /V1/pos/locations /:locationId Create, update, delete locations
GET /V1/pos/terminals /:terminalId List and fetch terminals
POST/PUT/DELETE /V1/pos/terminals /:terminalId Create, update, delete terminals
POST /V1/pos/terminals/activate Bind a device with a one-time activation code
POST /V1/pos/terminals/deactivate Release the device binding
POST /V1/pos/terminals/:terminalId/heartbeat Periodic check-in: device identity, open register session, config and staff hashes, license status
POST /V1/pos/terminals/:terminalId/license/refresh Force a license refresh from hyva.io

Staff and Roles

Method Route Purpose
GET /V1/pos/staff /:staffId List and fetch staff
POST/PUT/DELETE /V1/pos/staff /:staffId Create, update, delete staff
GET/POST/DELETE /V1/pos/staff/:staffId/locations /:locationId Read, assign, unassign location access
POST /V1/pos/staff/authenticate Email + passcode login; returns a staff session
POST /V1/pos/staff/session/validate Validate a staff session token
POST /V1/pos/staff/:staffId/unlock Clear a login lockout early
GET/POST/PUT/DELETE /V1/pos/roles /:roleId Role CRUD with granular permission keys

Receipts

Method Route Purpose
POST /V1/pos/receipts Sync a completed sale's receipt (idempotent by sale id)
GET /V1/pos/receipts /:receiptId /by-increment-id/:incrementId List and fetch receipts
POST /V1/pos/receipts/email Email a rendered receipt to the customer

Register Reports

Method Route Purpose
POST /V1/pos/register-reports Upload a register closing (idempotent by report ID)
GET /V1/pos/register-reports · /:reportId List closings, or the ones changed after a revision; fetch one

Held Carts

Method Route Purpose
GET /V1/pos/held-carts/location/:locationId The location's shared parked carts
POST /V1/pos/held-carts · /:heldCartId/recall Park a cart; claim a parked cart
DELETE /V1/pos/held-carts/:heldCartId · /uuid/:cartUuid Discard by id or by cart UUID

Credits

Method Route Purpose
GET /V1/pos/credits/balance/:customerId · /giftcard/:code Balances; gift-card validation
POST /V1/pos/credits/applicable What a cart may spend of a credit kind
POST /V1/pos/orders/:orderId/due-payments Collect the credit due an order still owes
GET /V1/pos/orders/:orderId/points-earned The reward points the vendor credited for an order

Customers and Pricing

Method Route Purpose
POST /V1/pos/customer-validate · /V1/pos/customers Pre-validate; create with boundary re-validation
POST /V1/pos/customer-prices Customer-specific prices from the resolver pool
GET /V1/pos/customers/:customerId/credit-limit Available credit for pay-by-invoice
GET /V1/pos/wishlist/:customerId The customer's wishlist at the register
GET /V1/pos/customers/:customerId/rule-usage/:ruleId How often the customer used a cart price rule and its coupon
GET /V1/pos/catalog-rule-prices · /V1/pos/fixed-product-taxes Catalog rule prices and fixed product taxes for the offline cache
GET /V1/pos/newsletter/status A customer email's newsletter state
POST /V1/pos/newsletter/subscribe · /unsubscribe Subscribe or unsubscribe an email
GET /V1/pos/customer-insights/:customerId The Customer Insights sheet's statistics and sections

RMA

Method Route Purpose
GET /V1/pos/rma/order/:orderId · /:rmaId · /open Returnables, single return, open-returns list
GET /V1/pos/rma/options · /eligibility/:orderId The provider's reasons, conditions and resolutions; what an order can still return
POST /V1/pos/rma · /process Create a return; one-call create + credit memo + resolution
POST /V1/pos/rma/:rmaId/process · /receive · /resolve · /settle · /comment The staged in-store workflow
PUT /V1/pos/rma/:rmaId/status Transition a return's status
POST /V1/pos/rma/:rmaId/cancel-refund · /close Cancel a parked in-store refund; close an open return
POST /V1/pos/refunds/preview The credit memo a refund would book, never saved
GET /V1/pos/rma/refund-attempts/:attemptId One refund attempt through the original payment's gateway
POST /V1/pos/rma/refund-attempts/:attemptId/reconcile · /resolve Settle an uncertain attempt: ask the gateway again, or record what its records show
POST /V1/pos/refund-approvals A manager's approval of one refund payout (Hyva_Pos::staff_manage)
POST /V1/pos/refund-operations/authorize Authorize a payout the register makes itself, before the money leaves
POST /V1/pos/refund-operations/:operationId/complete Complete an authorized register payout that no return's settle books

Fulfillment and Shipping

Method Route Purpose
GET /V1/pos/locations/:locationId/pickups The location's pickup queue
POST /V1/pos/orders/:orderId/pickup-completion · /pickup-cancellation Complete or cancel a pickup
GET /V1/pos/products/:childSku/bundle-parents Bundles containing this product
POST/GET /V1/pos/shipping-rates · /shipping-config · /carriers Rates and carrier configuration
POST/GET /V1/pos/orders/:orderId/ship-with-label · /V1/pos/shipments/:shipmentId/shipping-label Create and retrieve carrier labels

Layaway and Self-Checkout

Method Route Purpose
POST /V1/pos/layaways/:orderId/payments · /cancel Deposits and top-ups; cancellation with fee
POST /V1/pos/self-checkout/otp/request · /verify Email one-time-code sign-in for kiosk customers

Audit and Telemetry

Method Route Purpose
POST/GET /V1/pos/audit-log Submit device audit entries; list them (admin resource)
POST/GET /V1/pos/telemetry · /report Submit diagnostics; export the report (admin resource)
POST/GET /V1/pos/sale-events Submit approvals and interventions at the register; list them