Receipt Printer Setup: How to Connect and Print Orders

The RestaurantManage Print Agent is a lightweight Windows service that receives print commands from the cloud and sends them to your thermal receipt printer — enabling automatic receipt printing when orders are paid or when kitchen tickets need to be printed. The agent supports network printers (TCP port 9100), USB printers, and Windows spooler connections. This guide covers installation, configuration, printer connection, and troubleshooting.

How Does Receipt Printing Work?

The printing workflow is fully automated. When a cashier confirms payment or a kitchen ticket is triggered, the RestaurantManage backend generates the complete receipt as ESC/POS byte commands. These bytes are sent over a secure WebSocket connection (PrintHub) to the Print Agent running on a Windows PC in your restaurant. The agent decodes the data and forwards it directly to the connected thermal printer. The entire process takes under two seconds from payment confirmation to printed receipt.

The Complete Printing Pipeline

Understanding the full pipeline helps with troubleshooting. Here is the sequence of events every time a receipt or kitchen ticket is printed:

1. Payment confirmed: The cashier marks an order as paid in the cashier panel, or a kitchen ticket is manually triggered.
2. Backend formats the receipt: The RestaurantManage server runs ReceiptFormattingService, which builds the receipt layout using ReceiptBuilder and converts it to ESC/POS byte commands via EscPosCommands and EscPosRasterEncoder.
3. Data sent via PrintHub: The formatted receipt bytes (encoded as Base64) are broadcast over a secure WebSocket channel (SignalR PrintHub) to the correct Print Agent — identified by your restaurant ID.
4. Print Agent receives the job: The Windows service running on your local PC receives the Base64 payload, decodes it back to raw ESC/POS bytes, and identifies which printer to use.
5. Printer output: The decoded bytes are sent directly to the thermal printer via network TCP, Windows spooler, or USB — and the receipt is printed within seconds.

What Is Included on a Printed Receipt

Every receipt generated by RestaurantManage includes a complete set of transaction details. The header shows your restaurant name, address, and logo (if configured). The body includes the table number, a numbered list of all ordered items with quantities and unit prices, any applicable discounts, and an itemized tax breakdown by tax category. The footer shows the order total, payment method (cash, card, etc.), the date and time of payment, and an optional thank-you message. Kitchen tickets follow a simplified format showing only the table number, item names, quantities, and any item-level notes — designed for fast reading under kitchen conditions.

When Are Receipts Triggered

Receipts and kitchen tickets are triggered at two distinct moments. Customer receipts print automatically when the cashier confirms full or partial payment for an order — no manual action is required after that point. Kitchen tickets print when a new order is submitted from the cashier panel or the waiter mobile app. In both cases, the print job is handled entirely by the backend and routed to the Print Agent automatically. Authorized staff can also trigger a reprint from the admin dashboard if the original print was missed or garbled.

How Do I Install the Print Agent?

Installation takes about five minutes on any modern Windows PC. The PC must remain powered on during restaurant service hours, as the Print Agent runs as a background Windows service.

1. Download: Get the latest Print Agent installer from your admin dashboard or contact support.
2. Install: Run the installer on a Windows PC that will stay powered on during service hours.
3. Configure: Open config.json and enter your API base URL, restaurant ID, and agent secret key (provided by your admin).
4. Connect printer: Plug in your thermal printer via USB or connect it to the same network as the PC.
5. Start the service: Run the Print Agent — it connects to PrintHub automatically and shows a green status indicator.
6. Test print: Process a test payment from the cashier panel and verify the receipt prints correctly.

System Requirements

The Print Agent has minimal hardware requirements but does depend on a supported operating system and runtime:

• Operating system: Windows 10 (version 1909 or later) or Windows 11. The Print Agent is a Windows-only service and does not run on macOS or Linux.
• Runtime: .NET 8 Runtime must be installed. The installer will prompt you to download it if not already present — it is free from Microsoft.
• Internet connection: A stable internet connection is required to communicate with the RestaurantManage cloud. The agent reconnects automatically after brief outages.
• Network access: The PC must be able to reach the printer — either via USB cable or on the same local network segment (same router/switch).
• Processor and RAM: Any modern processor with at least 512 MB of free RAM is sufficient. The agent is very lightweight.

Running as a Windows Service

For production use, the Print Agent should be installed as a Windows service so it starts automatically when the PC boots — even before a user logs in. To register it as a service, right-click install-service.bat and choose Run as Administrator. This registers the agent with the Windows Service Control Manager under the name RestaurantPrintAgent. After installation, you can manage it from the Services panel (services.msc) or from the command line using sc start RestaurantPrintAgent and sc stop RestaurantPrintAgent. To remove the service, run uninstall-service.bat as Administrator.

Finding Your Restaurant ID and Secret Key

The Restaurant ID is the unique identifier for your restaurant in the RestaurantManage system. You can find it in the admin panel under Settings → Restaurant Information. The Agent Secret Key is a separate credential that authenticates the Print Agent with the PrintHub WebSocket endpoint — it is not the same as your user password. To generate or regenerate a secret key, go to Settings → Print Agent in the admin dashboard and click Generate New Key. Copy the key immediately and paste it into config.json — it will not be shown again after you navigate away. If you lose the key, simply generate a new one; the old key will be invalidated automatically.

What Printer Connection Types Are Supported?

The Print Agent supports three connection methods, with automatic fallback between them. Network printers, USB printers, and Windows spooler connections are all supported. The agent tries spooler first, then falls back to direct USB, and finally attempts UNC network shares.

Network Printers (Recommended)

Network printers are the recommended connection method for most restaurants. A network-connected thermal printer has its own IP address and accepts raw print data on TCP port 9100 — the standard port for ESC/POS printing. To set up a network printer, connect it to your router or switch with an Ethernet cable, then use the printer's built-in configuration page or front-panel menu to assign it a static IP address (e.g. 192.168.1.100). Enter this IP address and port 9100 in the Print Agent configuration. A static IP is important — if the printer receives a new IP from DHCP each time it restarts, print jobs will fail. Network printers are preferred over USB because they can be placed anywhere in the restaurant (or kitchen), the PC and printer do not need to be physically adjacent, and multiple PCs can share a single network printer.

USB and Windows Spooler Printers

USB thermal printers connect directly to the Windows PC running the Print Agent. After connecting the USB cable, install the manufacturer's Windows driver if required (many modern ESC/POS printers use a generic driver included in Windows). The Print Agent will detect the printer via Windows spooler — the same system used by all Windows applications. If the printer does not appear in the spooler, try the direct USB addressing method: the agent can write directly to USB device paths like \\\\?\\USB001 or parallel port paths like LPT1. USB printers are a good choice for smaller setups where the printer is located on or near the cashier desk.

Automatic Fallback Order

When a print job is received, the Print Agent tries connection methods in this order: 1) Windows Spooler — if the printer is registered in Windows and accessible via the spooler, this method is used first. 2) Direct USB — if spooler fails, the agent tries writing directly to USB device paths (USB001, USB002, etc.) and LPT ports. 3) UNC network share — as a last resort, the agent attempts to reach the printer via a Windows network share path (e.g. \\\\printserver\\receipt). If all three methods fail, the error is logged in the logs/ folder with details about which connection was attempted and why it failed.

How Do I Configure the Print Agent?

The Print Agent is configured through a single config.json file located in the installation directory. All settings are in plain text and take effect the next time the service starts (or restarts). There is no graphical interface for configuration — editing the file with any text editor is sufficient.

The config.json File Explained

The configuration file has three required fields and accepts optional printer settings:

• ApiBaseUrl: The base URL of your RestaurantManage server, for example <code>https://restaurantmanage.xyz</code>. Do not include a trailing slash. The Print Agent uses this URL to connect to PrintHub and to check for updates.
• RestaurantId: Your restaurant's unique identifier. You can find this in the admin dashboard under Settings → Restaurant Information.
• AgentSecretKey: The secret key generated in the admin panel under Settings → Print Agent. This key authenticates the agent with the server without requiring a user login. Keep it confidential.

A complete example config.json looks like this: {"ApiBaseUrl": "https://restaurantmanage.xyz", "RestaurantId": "your-restaurant-id", "AgentSecretKey": "your-secret-key"}. After editing the file, restart the Print Agent service for the changes to take effect.

Printer Name and IP Configuration

For network printers, you need the printer's IP address. To find it: most thermal printers print a configuration page when you hold the feed button during power-on — the IP address is listed there. Alternatively, check your router's DHCP client list for the printer's hostname. Once you have the IP, assign it as a static address in the printer's network settings so it never changes. For Windows spooler printers, the printer name must match exactly how it appears in Windows Settings → Printers & Scanners. Printer names are case-sensitive.

Log Files and Diagnostics

The Print Agent writes detailed logs to the logs/ subfolder inside the installation directory. Log files are named by date (e.g. log-2026-04-06.txt) and roll daily. Each log entry includes a timestamp, severity level (INFO, WARN, ERROR), and a description of what occurred. Common log messages include successful print confirmations, connection status changes, update check results, and error details when a print job fails. If you are troubleshooting a print failure, check the log file for the date of the issue — the exact error message will indicate whether the problem is network-related, authentication-related, or printer-related.

How Does Automatic Updating Work?

The Print Agent checks for updates approximately every 2.5 hours by calling the update endpoint on the RestaurantManage server. If a new version is available, it downloads the update package as a ZIP file to a pending updates folder, runs the installation script, and restarts the service automatically. This means your restaurant always runs the latest version without manual intervention. Update checks include a per-restaurant timing jitter to avoid all agents updating simultaneously. You can see the current agent version in the admin dashboard.

Troubleshooting Common Issues

Most print problems fall into one of three categories: connection issues, printer hardware issues, or configuration errors. The log files in the logs/ folder are the best starting point for diagnosing any problem.

Connection and Authentication Errors

• Agent won't connect to server: Verify that ApiBaseUrl in config.json is correct and reachable from the PC. Open a browser on the same PC and navigate to the API URL — you should see a response. Check that the PC has an active internet connection.
• Authentication failure (401 error in logs): The AgentSecretKey is incorrect or has been regenerated. Log into the admin dashboard, generate a new key under Settings → Print Agent, update config.json, and restart the service.
• Connection drops and reconnects repeatedly: This usually indicates a network instability issue. Switch from Wi-Fi to wired Ethernet. Check if a firewall or antivirus is blocking outbound WebSocket connections (the agent uses HTTPS port 443).
• Agent connects but receives no print jobs: Confirm that the Restaurant ID in config.json matches the one in your admin dashboard exactly (it is case-sensitive). Also verify that the Print Agent is enabled in Settings → Print Agent.

Print Quality and Encoding Issues

• Garbled characters or symbols on receipt: Your thermal printer may not fully support the ESC/POS command set used by RestaurantManage. Check the printer's documentation for ESC/POS compatibility. Most 58mm and 80mm thermal receipt printers manufactured after 2015 are compatible. Older label printers or inkjet printers will not work.
• Receipt prints but text is cut off: The paper width setting may be incorrect. RestaurantManage formats receipts for 80mm paper by default. If you are using a 58mm printer, contact support to enable the narrow paper mode.
• Receipt prints blank or only partial content: This can indicate a low paper roll or a clogged print head. Replace the paper and clean the print head with a dry cloth. If the problem persists, test the printer directly from Windows (print a test page) to isolate whether the issue is hardware or software.
• Special characters or Arabic/RTL text not printing correctly: Ensure your printer's character set is set to UTF-8 or the appropriate code page for your language. This setting is usually accessible in the printer's configuration menu.

Service Startup Failures

• Agent not starting as a Windows service: You must run install-service.bat as Administrator (right-click → Run as Administrator). Without elevated permissions, the service cannot be registered with the Windows Service Control Manager.
• Service starts then immediately stops: Check the Windows Event Viewer (eventvwr.msc) under Windows Logs → Application for error messages from RestaurantPrintAgent. Also check the logs/ folder for startup errors. Common causes are a missing or malformed config.json, a missing .NET 8 runtime, or a port conflict.
• .NET runtime missing: Download and install the .NET 8 Runtime from https://dotnet.microsoft.com. After installation, restart the Print Agent service.
• Firewall blocking the agent: Windows Defender or a third-party firewall may block the agent's outbound connection. Add an exception for the Print Agent executable in your firewall settings.

Related Guides

• Cashier panel: How to process payments that trigger receipt printing
• Kitchen display: How kitchen ticket printing integrates with the order flow
• Getting started: Full setup guide from registration to first order