Retailer OS Docs

Appearance

Hardware & cash drawer ​

Retailer OS runs in your web browser, so most counter hardware works the way it does with any website: receipts print through your computer's print dialog, and a barcode scanner types straight into the POS. Card readers pair through Stripe, and a cash drawer can open by itself when a cashier takes cash, through your receipt printer. This page covers what works where, and how to connect each one.

Receipt printers ​

When a sale finishes and the cashier chooses to print, Retailer OS opens the receipt and your browser's print dialog. Pick your receipt printer there. Any printer installed on the computer works. What goes on the receipt is covered in Receipts.

Barcode scanners ​

A USB or Bluetooth barcode scanner that works like a keyboard needs no setup; most scanners work this way out of the box. Scan an item while the POS search box is active, and it's added to the sale. See Ringing up a sale.

Card readers ​

Retailer OS takes in-store card payments on Stripe smart readers, such as the BBPOS WisePOS E. You set them up under Setup → Payments (owners and admins, by default).

  1. Connect Stripe under Setup → Payments, and finish onboarding so your account can take charges. The In-store card payments card appears once it can.
  2. Click Enable Terminal.
  3. On the reader, connect to your store's Wi-Fi, then go to Settings → Generate pairing code. Three short words appear on the screen.
  4. Type them in Pairing code, give the reader a Label (such as Register 1), and click Pair.

Until Terminal is on, the POS records card payments by hand, without a reader.

Cash drawer ​

A cash drawer doesn't connect to the computer. It plugs into the receipt printer, which opens it with a pulse. When a cashier taps Cash at checkout, Retailer OS sends the "open" command to the printer. The drawer is optional, and it's off until you connect it under Setup → Payments (owners and admins, by default).

Connect a USB printer's drawer ​

This works in Chrome and Edge. Safari and Firefox can't reach USB devices.

  1. Plug the drawer into the receipt printer, and the printer into the computer by USB.
  2. In Chrome or Edge, open Setup → Payments and find the Cash drawer card.
  3. Click Detect USB drawer, pick your receipt printer in the browser's prompt, and confirm.
  4. Click Open drawer to test it.

The browser remembers the printer on that computer, so it reconnects on its own after this.

Connect through a print relay ​

Browsers can't send data to a network printer directly. For a network printer, you need a print relay: a small program on the till computer that takes print data over HTTP and passes it to the printer. Retailer OS doesn't include one.

  1. Run the relay on the till computer, for example at http://localhost:8080.
  2. Open Setup → Payments, find the Cash drawer card, and click Use a network relay.
  3. Enter a Name and the Print-relay URL, including http://, then click Connect.
  4. Click Open drawer to test it.

Use a localhost address. Retailer OS runs over HTTPS, so browsers block it from calling a plain network address such as http://192.168.1.50. Retailer OS sends the open command to the URL you enter and checks the relay by loading that same URL, so the relay has to accept both, and allow requests from app.retaileros.ai.

At the register ​

Once the drawer is connected, the POS payment panel shows Drawer connected or Drawer offline, and the drawer opens as soon as the cashier taps Cash. A sale never waits on the drawer. If it can't open, the cashier sees Couldn't open the cash drawer and finishes the sale as normal.

WARNING

For now, the register can open the drawer only for people with the Edit tenant profile, timezone, currency permission. Owners and admins have it by default. Everyone else sees Couldn't open the cash drawer when they tap Cash, and no drawer status appears. You can grant that permission under Setup → Team, but it also lets the person edit your store settings.

Several tills ​

Retailer OS keeps one cash drawer setting for the whole business, not one per counter.

  • Print relay: run the relay at the same localhost address on every till computer, and the one setting works on all of them.
  • USB: each computer's browser has to be paired once, but Detect USB drawer only appears when no drawer is set up. To pair another till, remove the drawer on that till and detect it again. The first till keeps working as long as both use the same printer model.

Test or remove the drawer ​

On the Cash drawer card:

  • Open drawer sends a test pulse.
  • The badge reads Connected, Offline, or Off (no drawer set up).
  • The trash can removes the drawer. The register then stops opening it.

The Hardware page ​

Setup → Hardware (/setup/hardware) lists the devices registered for your business: printers, scanners, cash drawers, scales, customer-facing displays, and PIN pads. It needs the Edit tenant profile, timezone, currency permission (owners and admins, by default).

  • Register device adds one, with its kind, name, connection, endpoint, and serial number. The trash can removes one.
  • Cash drawers get an Open drawer test button here too. Set a USB drawer up from Setup → Payments, though, since pairing happens there.

Keep two things in mind:

  • Registering a printer, scanner, scale, display, or PIN pad only adds it to this list. It doesn't change how the device works: receipts still print through the browser, scanners still type into the POS, and card readers pair under Setup → Payments.
  • The status badge depends on devices reporting in, and devices used through the browser don't report in yet. Most devices show stale here even when they work. Check a cash drawer's live status on Setup → Payments or at the register instead.

In the desktop app ​

The Retailer OS desktop app runs the same screens as the browser, with one difference for the cash drawer. The app only allows connections to Retailer OS's own servers, so it can't reach a print relay, and Detect USB drawer only appears if the app's built-in browser can reach USB devices. On a till that needs its cash drawer to open, run Retailer OS in Chrome or Edge.

Common questions ​

Q. A cashier sees "Couldn't open the cash drawer" when they tap Cash. A. The register can only look up the drawer for people with Edit tenant profile, timezone, currency (see the warning above). If it happens to an owner or admin, check that the relay is running, or that the USB printer is on and plugged in. Either way, the sale still goes through.

Q. The drawer shows Offline. A. With USB, open Retailer OS in the same browser on the computer you paired, with the printer on and plugged in. With a relay, check that it's running at the URL you entered.

Q. Can I open the drawer without a sale? A. Yes. Open drawer on the Cash drawer card, or on the Hardware page, sends a test pulse. Both are available to owners and admins, by default.