# 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 |

## WCPOS Cloud Print — the relay[​](#relay "Direct link to WCPOS Cloud Print — the relay")

When you set up a **polling** printer (Star CloudPRNT or Epson Server Direct Print), the poll URL WCPOS gives you points at **cloudprint.wcpos.com**, not at your own site. That's **WCPOS Cloud Print** — a free relay run by WCPOS that sits between your printer and your store.

**Why it exists.** Receipt printers run small, rarely-updated firmware. Many can't complete a secure connection to a store on modern hosting: newer TLS versions, newer certificate authorities, or a CDN/firewall in front of the site (Cloudflare is a common culprit) will refuse the printer — or be refused by it. The symptom is a printer stuck on **Waiting** forever even though every setting is correct. The relay presents printers with a connection that older firmware can always negotiate, and passes their traffic through to your store.

**How it works:**

* Your site connects to the relay **automatically** the first time you open the Cloud Print settings — there's nothing to enable or configure.
* The printer polls `cloudprint.wcpos.com`; the relay forwards the request to your store and returns your store's answer. Print jobs pass **through** the relay — they are never stored on it.
* The relay absorbs most idle polling, so an idle printer costs your site about one request per minute instead of one every few seconds.
* If your site can't connect to the relay (for example, a local development site the relay can't reach), WCPOS automatically falls back to direct-to-site URLs.

Prefer a direct connection?

Every printer's setup screen has an **Advanced** disclosure showing the direct-to-site URL. Use it if you know your hosting is printer-friendly, or if you'd rather not route jobs through the relay. Developers can switch the relay off site-wide with one line:

```
add_filter( 'wcpos_cloud_print_relay_enabled', '__return_false' );
```

Before WCPOS 2.0 this filter was named `woocommerce_pos_cloud_print_relay_enabled`; that name still works but is deprecated since 2.0 and is removed in 2.2 at the earliest (see [Hook naming](/extensions.md#hook-naming)).

**What the relay can see.** Connecting shares your site URL with wcpos.com, and print jobs — receipt contents, which include order details — transit the relay on their way to the printer. Nothing is retained. Full details are in the [privacy policy](https://wcpos.com/privacy).

## 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 URL normally points at **cloudprint.wcpos.com** — that's the [WCPOS Cloud Print relay](#relay), and it's what you want; the direct-to-site URL sits behind the **Advanced** disclosure. 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**, plus **when** it fires and **how many copies** to print, for example:

> Print **every order** to **Kitchen** using **Kitchen Ticket**, **once paid**, **×2**.

A rule can trigger **when the order is created** or **only once it's paid** — so a kitchen ticket can fire the moment an order is placed while a customer receipt waits for payment — and you can set the **number of copies** when a station needs more than one. When a matching order reaches the chosen trigger, 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.

Rendering fallbacks for stubborn printers

**Star CloudPRNT** negotiates the media type with the printer and falls back to plain text (`text/plain`) when a printer won't accept the richer format. For Star printers whose firmware can't decode StarPRNT commands, WCPOS can render the receipt **server-side as a PNG image** and send that instead — so the receipt still prints rather than failing.

## The print queue[​](#print-queue "Direct link to The print queue")

Every job for a cloud printer sits in a queue on your site until the printer collects it (polling printers) or the provider confirms delivery. **WP Admin > POS > Settings > Cloud Print** shows the queue below your printers:

* **Filter** by printer or by status — **Waiting**, **Printing**, **Printed**, **Failed**, **Cancelled** — with live counts.
* Each row shows how long the receipt has been **waiting** and links to the WooCommerce **order** it prints.
* **Cancel** waiting jobs one at a time, in bulk, or for a whole printer at once. **Retry** re-queues a failed job.

If a printer has waiting jobs but hasn't collected anything for more than a few minutes, a **warning banner** names the printer, shows how many receipts are backed up and for how long, and offers **Cancel all** — a backlog can never build up silently while a printer is unplugged.

## 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.
* If you entered the **direct-to-site URL** (from the Advanced disclosure) and the printer still won't connect, switch to the standard **cloudprint.wcpos.com** URL — many printers can't negotiate a secure connection with modern hosting, which is [exactly what the relay fixes](#relay).

Why does my printer URL point to cloudprint.wcpos.com?

That's [WCPOS Cloud Print](#relay), the free relay that gives printers a connection their firmware can always negotiate and passes their print jobs through to your store. It's on automatically, jobs are never stored on it, and the direct-to-site URL is always available under the printer's **Advanced** disclosure if you prefer.

I set my printer up before the relay existed — do I need to change anything?

No — URLs already saved in a printer's configuration keep working. If that printer is **stuck on Waiting**, though, its firmware is likely one that can't connect to your hosting directly: open **Setup & token** on the printer card, regenerate the token, and enter the new **cloudprint.wcpos.com** URL and token in the printer's configuration.

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)
