# Cloud Printing

Cloud printing lets WCPOS send receipts to a printer that isn't directly connected to the device running the till. Set it up once in WP Admin and your orders print to a kitchen printer, a back-office printer, or a printer in another room — without each device having to discover and pair with the hardware itself.

## What is cloud printing?[​](#what-is-cloud-printing "Direct link to What is cloud printing?")

With **local printing**, the device running the POS talks straight to the printer over USB, Bluetooth, or the local network. That's the right choice when the printer sits next to the till — see [Printer Setup](/hardware/printers.md) for connecting USB, Bluetooth, and network printers on the same device.

**Cloud printing** is for everything else: a printer in a different location, on a different network, or one you want every device to share without configuring it on each one. There are two delivery models:

* **Polling printers.** The printer reaches out to WCPOS over the internet on a schedule, asks "do you have anything for me?", and pulls down any waiting jobs. WCPOS never connects to the printer — the printer always starts the conversation. This is how **Star CloudPRNT** and **Epson Server Direct Print** work.
* **Hosted relay providers.** WCPOS submits the print job to a hosted service, and that service delivers it to the printer. This is how **Star Online** and **PrintNode** work. Star Online delivers to Star CloudPRNT printers registered in your stario.online account; PrintNode delivers through its desktop client to almost any printer that computer can already print to.

Why a printer that polls?

A polling printer doesn't need an open port, a static IP, or any firewall changes — it only ever makes outbound requests. That makes it ideal for a printer at a remote site or behind a router you don't control. The trade-off is a short delay: the printer only prints when its next poll comes around.

## Choosing a provider[​](#providers "Direct link to Choosing a provider")

Pick the provider that matches your hardware.

#### Star CloudPRNT

For Star thermal printers running the **CloudPRNT** firmware. The printer polls WCPOS and pulls jobs. Receipts are rendered to the printer's native commands. Needs a thermal template.

#### Star Online

For Star printers registered in a **stario.online** account. WCPOS submits Star Document Markup to Star's hosted service, and the printer collects it from Star Online. Needs a thermal template.

#### Epson Server Direct Print

For Epson ePOS printers that support **Server Direct Print**. The printer polls WCPOS and pulls jobs as ePOS-Print XML. Needs a thermal template.

#### PrintNode

Works with virtually any printer your computer can print to, on any OS, via the **PrintNode desktop client**. WCPOS submits a PDF, so you can use any template — including full-page HTML invoices.

| Provider                      | Hardware                                     | How jobs flow                                     | Templates    |
| ----------------------------- | -------------------------------------------- | ------------------------------------------------- | ------------ |
| **Star CloudPRNT**            | Star thermal printer with CloudPRNT firmware | Printer polls WCPOS                               | Thermal only |
| **Star Online**               | Star printer registered in stario.online     | WCPOS submits Star Document Markup to Star Online | Thermal only |
| **Epson Server Direct Print** | Epson ePOS printer with Server Direct Print  | Printer polls WCPOS                               | Thermal only |
| **PrintNode**                 | Any OS-connected printer + PrintNode client  | WCPOS submits a PDF to PrintNode                  | Any template |

## Setting up a cloud printer[​](#setup "Direct link to Setting up a cloud printer")

Cloud printers are configured once in WP Admin and shared across every device — unlike local printers, which are stored per device.

Go to **WP Admin > POS > Settings > Cloud Print** and click **Add printer**. Give it a **name** (for example "Kitchen" or "Back office"). WCPOS derives a stable **printer ID** from the printer automatically — it never changes, so it's safe to reference from a printer's firmware configuration.

After the printer exists, configure the provider end.

### Star or Epson (polling printers)[​](#setup-polling "Direct link to Star or Epson (polling printers)")

1

#### Add the printer in WCPOS

In **WP Admin > POS > Settings > Cloud Print**, add a printer and choose **Star CloudPRNT** or **Epson Server Direct Print** as the provider. WCPOS generates a **poll URL** and a **one-time token** for that printer.

2

#### Copy the poll URL and token

Copy the generated poll URL and token. The **token is shown only once** — if you lose it, regenerate a new one from the printer card and update the printer with the new value.

3

#### Enter them in the printer's configuration

Open the printer's configuration page — the **CloudPRNT** settings for Star, or the **Server Direct Print** settings for Epson — and paste in the poll URL and token. Set the poll interval if the printer asks for one (a few seconds is typical). Save and reboot the printer if required.

Within a poll cycle the printer checks in, and its status in WCPOS changes from **Waiting** to **Connected**.

### PrintNode[​](#setup-printnode "Direct link to PrintNode")

1

#### Install the PrintNode desktop client

On a computer that can already print to your target printer, install the **PrintNode client** and sign in. The client must stay running and online for jobs to print.

2

#### Get a PrintNode API key

In your PrintNode account, create an **API key**. This is what lets WCPOS submit jobs to your PrintNode account.

3

#### Enter the API key in WCPOS

Add a printer in **WP Admin > POS > Settings > Cloud Print**, choose **PrintNode** as the provider, and paste in the API key. WCPOS uses it to fetch the list of printers registered to your PrintNode account.

4

#### Select the printer

Choose the target printer from the list of printers reported by the PrintNode client, then save. WCPOS will submit jobs for this printer to PrintNode, and the client prints them.

### Star Online[​](#setup-star-online "Direct link to Star Online")

Use Star Online when your Star printer is already registered to a **stario.online** account and you want Star's hosted service to handle delivery.

1

#### Get the CloudPRNT URL

In stario.online, open **Device Groups** and copy the group's **CloudPRNT URL**. It should look like `https://device.stario.online/cloudprnt/...` or `https://eu-device.stario.online/cloudprnt/...`.

2

#### Create an API key with permissions

In stario.online, create an API key for WCPOS. The key must have permission to list devices and print to them. At minimum, enable:

* **EnumDevices** — required when WCPOS fetches the device list
* **ViewDevice** — used for device status checks
* **PrintToDevice** — required to submit print jobs
* **ViewDeviceGroups** — recommended for group lookup and diagnostics

An API key can exist and still fail if these permissions are not enabled.

3

#### Enter the URL and API key in WCPOS

Add a printer in **WP Admin > POS > Settings > Cloud Print**, choose **Star Online** as the provider, then paste the CloudPRNT URL and API key. Click **Fetch my devices**.

4

#### Select the Star device

Choose the printer from the device list and save. WCPOS stores the API key server-side and uses the selected device's access identifier when submitting jobs to Star Online.

## Auto-print rules[​](#auto-print "Direct link to Auto-print rules")

Auto-print rules decide what prints where, automatically — written as plain sentences. A rule is **scope × printer × template**, for example:

> Print **every order** to **Kitchen** using **Kitchen Ticket**.

When a matching order completes, WCPOS renders the chosen **template** server-side into the format the printer needs and queues it — there's nothing for the cashier to do.

Template compatibility matters

Star and Epson printers can only use **thermal** templates, because the job has to be rendered to the printer's native command language (Star Document Markup or ESC/POS for Star, ePOS-Print for Epson). PrintNode can use **any** template — thermal or full-page HTML — because the job is rendered to a **PDF**. If a template doesn't appear as an option for a printer, it's because the printer can't render that format. See [Thermal Templates](/receipts/thermal-templates.md) for creating thermal layouts.

## Per-store printers (Pro)[​](#per-store-printers "Direct link to Per-store printers (Pro)")

Pro Feature

Per-store print routing requires [WCPOS Pro](/getting-started/pro-license.md) and a [multi-store](/stores/.md) setup.

By default, auto-print rules are global — every store shares them. With Pro, you can give an individual store its **own** cloud-print rules so its orders print to its own printers (a kitchen ticket at one location shouldn't print in another).

Edit a store under **POS → Stores**, open its **Cloud Printing** section, and **Add rule**. Each rule is:

* **Printer ID** — the stable ID of the cloud printer to send to
* **Scope** — **POS orders only** (default), **Online orders only**, or **Every order**
* **Format** — **StarPRNT** (default), **ESC/POS**, **Epson ePOS-Print**, or **HTML**

When an order belongs to a store that has its own rules, WCPOS routes it to that store's printers. If a store has **no** rules of its own, it **falls back to the global** auto-print rules — so you only need to configure the stores that differ.

## Manual printing[​](#manual "Direct link to Manual printing")

You don't have to wait for an auto-print rule. From the **checkout / receipt screen**, a cashier can send a receipt to a cloud printer on demand — handy for reprints or for routing a one-off ticket to a specific printer.

How the receipt is produced depends on the printer:

* **Star CloudPRNT** — the receipt is rendered **on the device** and handed to the printer through CloudPRNT.
* **Star Online, Epson, and PrintNode** — the receipt is rendered **on the server** from the selected order and template, then delivered to the printer or hosted relay.

## Test print & connection status[​](#status "Direct link to Test print & connection status")

Each printer card has a **Test print** button that sends a short diagnostic so you can confirm the printer is reachable and the format is right before relying on it for real orders.

The card also shows a live status:

| Provider                   | Status        | Meaning                                                                  |
| -------------------------- | ------------- | ------------------------------------------------------------------------ |
| **Star CloudPRNT / Epson** | **Waiting**   | The printer hasn't checked in yet — WCPOS is waiting for its first poll. |
| **Star CloudPRNT / Epson** | **Connected** | The printer polled WCPOS recently and is collecting jobs.                |
| **Star Online**            | **Online**    | Star Online reports the selected device is available.                    |
| **Star Online**            | **Offline**   | Star Online reports the selected device is not available.                |
| **Star Online**            | **Unknown**   | WCPOS could not confirm the device status from Star Online.              |
| **PrintNode**              | **Online**    | The PrintNode service reports the client and printer are available.      |
| **PrintNode**              | **Offline**   | PrintNode reports the client or printer is unavailable.                  |

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

Printer stuck on Waiting

A polling printer that never leaves **Waiting** has never successfully reached WCPOS. Check:

* The **poll URL and token** in the printer's firmware exactly match what WCPOS generated. A single wrong character means every poll is rejected — regenerate the token in WCPOS and re-enter it if you're unsure.
* The printer can actually **reach your site** over the internet (correct DNS, no firewall blocking outbound HTTPS, valid SSL certificate on your store).
* **Polling is enabled** in the printer's CloudPRNT / Server Direct Print configuration, with a sensible interval. Reboot the printer after changing its settings.

Star Online says the API key is unauthorised or forbidden

Star Online separates **authentication** from **permissions**:

* **401 / authentication failed** means the API key itself was not accepted. Check that the key was copied correctly, has not been revoked, and belongs to the expected Star Online account/region.
* **403 / forbidden** means the API key was accepted but is not authorised for the requested action. Edit the key in stario.online and enable the required permissions, especially **EnumDevices** for **Fetch my devices** and **PrintToDevice** for printing.

If **Fetch my devices** succeeds but no printers appear, check the stario.online **Device Groups** page. The group must contain at least one connected device, and the CloudPRNT URL in WCPOS must point to that same group.

PrintNode job never prints

The job reached PrintNode but didn't come out of the printer. Check:

* The **PrintNode desktop client is running and online** on the computer connected to the printer. If the computer is asleep or the client is closed, nothing prints.
* You selected the **correct printer** in WCPOS — the name must match the printer the client reports.
* The **API key is valid** and hasn't been revoked. Re-enter it if PrintNode shows the printer as Offline.

My template isn't selectable for a Star or Epson printer

Only **thermal** templates work on Star and Epson cloud printers, because the receipt has to be rendered to ESC/POS or ePOS-Print commands. HTML and full-page templates can't be expressed in those formats, so they're hidden for these printers.

Either choose a [thermal template](/receipts/thermal-templates.md), or use a **PrintNode** printer — PrintNode renders to PDF, so it can print any template.

## Related Documentation[​](#related-documentation "Direct link to Related Documentation")

[Printer SetupConnect a printer on the same device or network](/hardware/printers.md)

[TemplatesThe receipt template system](/receipts/.md)

[Thermal TemplatesBuild ESC/POS layouts for Star and Epson printers](/receipts/thermal-templates.md)