printforge / guides / print receipts from a web app

How to print receipts from a web app

You've built the ordering flow, the payment works, and now the kitchen needs a ticket on paper. This is where teams discover that the browser — the platform their whole app lives on — cannot talk to a receipt printer. Here's why, and the three architectures that actually solve it.

Why the browser can't just print

Receipt printers are not "printers" in the office sense. A thermal receipt printer is a serial device that speaks ESC/POS — a byte-level command language for feeding paper, styling text, cutting, and kicking open the cash drawer. Getting a receipt out means delivering exact bytes to a USB or network device.

Browsers deliberately can't do that. Web pages can't open raw sockets or write to USB without per-session permission prompts, and window.print() is the opposite of what you want: it pops a dialog, paginates for A4/Letter through the OS driver, and produces something that looks like a fax of your CSS. Silent, unattended printing — the thing a kitchen needs — is exactly what the browser security model forbids.

So every real solution moves the printing out of the page and into a small program running near the printer. The architectures differ only in who talks to that program.

The three architectures

The complete printforge integration

Two moving parts. First, the agent — on the machine next to the printer (anything with Node 18+; no installer, no inbound ports). Download it from /agent.js, create a bridge in the dashboard (or POST /v1/bridges) to get its pfb_ device token, then:

# one command — the agent connects outward and long-polls for work
PRINTFORGE_URL=https://printforge.yagnotech.com \
PRINTFORGE_DEVICE_TOKEN=pfb_YOUR_DEVICE_TOKEN \
node agent.js

Second, the job — from your backend, a webhook, or plain curl:

curl -X POST https://printforge.yagnotech.com/v1/jobs \
  -H "authorization: Bearer sk_pf_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "printerId": "YOUR_PRINTER_ID",
    "contentType": "receipt_json",
    "dedupeKey": "order-1042",
    "content": {
      "header": "ACME CAFE\n123 King St W",
      "lines":  [{ "name": "Cheeseburger", "qty": 2, "price": 25.98 },
                 { "name": "Fries",        "qty": 1, "price": 4.50 }],
      "totals": [{ "label": "Subtotal", "amount": 30.48 },
                 { "label": "TOTAL",    "amount": 34.44 }],
      "footer": "Thank you!"
    }
  }'

{ "job": { "state": "queued", "dedupeKey": "order-1042", … }, "replayed": false }

The agent claims the job, prints it, and acks — the job's state walks queued → dispatched → printed (or failed, with the reason and up to 3 automatic retries). Two details worth stealing for any implementation of pattern #2:

• Idempotent submits. The dedupeKey ties the job to your order ID: if your webhook fires twice, the second call replays the first job ("replayed": true) instead of printing the receipt twice. Checkout code retries; kitchens shouldn't see it.
• Outbound-only agents. The agent long-polls GET /bridge/v1/jobs?wait=25 over HTTPS. Nothing ever dials into the shop network, so there's no port-forwarding conversation with anyone's router.

Which one should you pick?

• Offline-first, browser-driven, no vendor: the local-helper pattern (#1). Budget for installing and maintaining the helper on every till, and accept that only open browser sessions can print.
• Server-driven printing at fleet scale: cloud dispatch (#2/#3). If your workload is PDFs to driver-installed printers, PrintNode's client-side rendering is the stronger fit; if it's receipts and tickets across many machines, that's the shape printforge was built for — the printforge vs PrintNode comparison puts the published numbers side by side.
• Just exploring? The live demo runs this exact pipeline against a virtual printer in your browser — no signup, nothing to install.