Box Retail Rails
Box Retail Rails are the in-person selling surface for a box. They pair device-linked client SDKs (a till app a merchant’s staff run on a phone or tablet) with the box’s retail-rails (RR) engine to enroll a terminal to a single merchant, sync the catalog, run a cart, take payments, and manage cashier sessions, all over HTTPS against the same box engine the dashboard and storefront use.
Unlike the merchant dashboard (the browser admin console) and the storefront render (the public shopfront), the retail rails are the hardware-till surface for selling face to face.
Clients
Where it sits
- A retail client talks only to the box engine, the same engine the dashboard and storefront use.
- A device is paired and approved from the dashboard (the merchant decides which store a device belongs to), then enrolls with a hardware-backed signing key.
- Once enrolled, the device stays linked to that one merchant across app relaunches until it is explicitly unlinked.
Device linking model
A till is bound to exactly one merchant, enforced by the client SDK (and again by the RR engine at enrollment):
Request pairing
A fresh device requests a pairing code (RFC 8628 device-authorization flow).
Approve from the dashboard
A manager approves the device from the merchant dashboard, which decides the merchant the device belongs to.
Enroll
The device generates a hardware-backed key (e.g. the Android Keystore) and enrolls; from then on, every request is signed with that key.
Stay linked
Enrollment is persisted by the client SDK (device id + signing key), so the till
resumes linked after relaunch. requestPairing() and enroll() refuse to run
on an already-enrolled device; you must unlink() first to move the hardware
to a different merchant.
The single-merchant rule is defended on both ends: the client SDK blocks re-pairing a linked device, and the RR engine rejects a device key that is already live under another merchant at enrollment time.
Reconciliation
Till sales carry the dashboard order number (e.g. POS-481204), shown as the
primary reference in the app’s sales history with the terminal transaction id in
the sale detail. This lets in-store sales reconcile one-to-one against the orders
the merchant sees in the dashboard.