> Tillcast is live: the API at https://api.tillcast.com/v1 and the dashboard at https://dashboard.tillcast.com. A key prints on real printers, so do not call the API unless asked. A job carries its receipt as "document", an array of blocks (the recommended way), or as "receiptline", ReceiptLine text, exactly one of the two: read https://docs.tillcast.com/create-a-print-job.md and https://docs.tillcast.com/concepts/documents.md before you write a job body. Do not code against what does not exist yet: webhooks, a template language, stored templates (a job has no template field), OAuth connections and connectors for Make, Zapier and n8n, and OAuth sign-in for the MCP server. SDKs for TypeScript (@tillcast/sdk, version 0.2.0 or later for blocks) and Python (tillcast) exist as pre-1.0 versions. To show a receipt in a web page without printing, there are the npm packages @tillcast/preview and @tillcast/html-render (0.x, no API key, no call to Tillcast to draw): read https://docs.tillcast.com/preview-a-receipt.md. The docs are the source of truth: check the index https://docs.tillcast.com/llms.txt and https://docs.tillcast.com/roadmap.md before you code against anything. For clean Markdown of any page, append .md to the page URL. The Tillcast MCP server is live at https://api.tillcast.com/mcp and takes an API key as a bearer token (setup: https://docs.tillcast.com/connect-an-ai-assistant.md). It acts on the live account and its tools print on real paper, so do not connect to it or call its tools unless the owner asked you to. The MCP server at https://docs.tillcast.com/_mcp/server is a different one: it only searches these docs and cannot call the Tillcast API.

# Set up an Epson printer

> How to add an Epson printer to Tillcast, enter the printer URL in the Server Direct Print settings of its Web Config and check its line width on paper, and what has and has not been checked on a device.

> **Printed on one unit, not checked on other models**
>
> The full test page, with every type style, a table, images, barcodes and QR codes, has been printed through Server Direct Print on an Epson TM-m30III-H, and every section came out. Other Epson models, and other variants of the TM-m30III, have not been checked on a device, and neither has how an ordinary receipt looks on paper. Recognising an Epson from its first connection, and the sheet that checks its line width, have not been checked on a device either. The menu names below come from Epson's Web Config reference guide and from two vendors' TM-m30III setup guides, not from a session with the printer. Menu names differ between firmware versions, so look for the words in bold and expect small differences.

An Epson printer polls Tillcast with **Server Direct Print**: it posts to the printer URL, gets the job as XML with ESC/POS commands, prints it and posts the result. Only models that have Server Direct Print work. See [Supported printers](/printers/supported-printers).

## Before you start

* A printer with Server Direct Print, on a network that allows outgoing HTTPS (port 443) and DNS. No VPN, port forwarding or local server is needed.
* A computer on the same network as the printer, and the printer's IP address. Print the network status sheet of the printer, or look the address up in your router. The sequence of buttons is model specific, so check the printer's manual.
* The administrator password of the printer's Web Config page. See Epson's manual for the initial one.

## Step 1: add the printer

In the dashboard press **Add printer**, type a name and choose the **Paper width**, 58 mm or 80 mm. Tillcast recognises an Epson by what it sends when it first connects, so you do not have to say which maker it is. With the API, send `paper_width` and nothing that names the maker, or name the maker yourself.

#### By paper width

```bash wordWrap
curl https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Idempotency-Key: reception-epson-paper-1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Reception Epson", "paper_width": "80mm"}'
```

#### Epson named

```bash wordWrap
curl https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Idempotency-Key: reception-epson-1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Reception Epson", "vendor": "epson", "profile": "epson-80mm-48"}'
```

To name the maker in the dashboard, open **Advanced** in the Add printer dialog and choose **Epson** as the **Maker**.

* A printer added by its paper width reads `"vendor": "star"`, with `"vendor_source": "default"` and `"detection": "pending"`, until it first connects. Then it reads `epson` and `vendor_source` is `detected`. See [Add a printer by its paper width](/printers/profiles#add-a-printer-by-its-paper-width).
* A maker that you name cannot be changed afterwards. A printer added as a Star, by name or without `paper_width`, does not understand an Epson: it never shows as connected, and its test page cannot print on an Epson. Delete it and add it again.
* An Epson reports neither its model nor its paper width. Added by its paper width, it prints for the default of its paper until you check its line width in step 4: `epson-80mm-48`, 48 columns on 80 mm paper, or `epson-58mm-35` on 58 mm paper. Added with the maker named, choose the [profile](/printers/profiles) of your paper yourself.
* The answer holds the printer URL in `url`, once. Keep it until you have typed it into the printer. A replay of the same request answers `url: null`.
* An Epson takes no [welcome receipt](/printers/first-connection) and no allowed device. It reports no MAC address, and `allowed_mac` is refused. The dashboard shows its brand and model as not known, for good.

## Step 2: enter the URL in the printer

1. Open `http://<epson-ip>/` in a browser on the same network. Some firmware answers on `https://` with a certificate of its own, and the browser warns about it. Choose **Advanced Settings**, then **Administrator Login**, and log in.
2. Check the printer's **date and time** first. It should follow a time server. A certificate is checked against the clock.
3. Open **TM-i Settings**, then **Server Direct Print**. One guide puts it under Services. In the group **Server Direct Print Setting** set the fields below.
4. Press **Apply & Restart**. The settings apply after the restart.

| Setting                      | Value                                                                                                                                                                                                                      |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Server Direct Print**      | Enable                                                                                                                                                                                                                     |
| **Server1**, **URL**         | The whole printer URL, exactly, `https://<customer code>.print.tillcast.com/<secret>`. **No trailing slash.** A path with a trailing slash is answered with a bare `404`, so the printer never connects. Never `localhost` |
| **Server1**, **Interval(s)** | `5` seconds. Keep it at 60 or less                                                                                                                                                                                         |
| **ID** and **Password**      | Empty. The URL is the credential and Tillcast does not read an `Authorization` header. If the form will not save with them empty, put a short throwaway value in both, never a password you use elsewhere                  |
| **URL Encode**               | Leave the default                                                                                                                                                                                                          |
| **Name**                     | Leave the default                                                                                                                                                                                                          |
| **Server Authentication**    | **Enable**. This checks Tillcast's certificate. A test with the check off proves nothing about the certificate chain                                                                                                       |
| **ePOS-Print**               | Must read **Enable**. The answer Tillcast sends is ePOS-Print XML, and a printer with it off may reject it. If it is greyed out while Server Direct Print is enabled, carry on                                             |

Do not photograph the URL field and do not put the URL in tickets or chat. See [Printer URL](/concepts/printer-url). For a printer added by its paper width, let the printer be the first to use the address: a request that is shaped like an Epson's first call and gets there first decides the maker.

## Step 3: check that it polls

Open the printer's page in the dashboard. Within a poll or two after the restart its status turns from **Never connected** to **Online**. Reload the page, because it does not refresh itself. **Last seen** is written at most once a minute, so it can stay the same for most of a minute.

A printer added by its paper width says **Waiting for the printer's first connection** until then. After it, its **Maker** reads **Epson · recognised when it connected**, and the page says **Check the line width**: go on to step 4.

Then press **Test print** on the printer's page (for a printer added by its paper width, check its line width first). The job goes **Queued**, **Delivered** and **Printed**, or **Failed**. At a 5 second interval the paper should come within about 5 to 10 seconds. You can do the same with `POST /v1/printers/{printer}/test-print`. See [First connection](/printers/first-connection#test-print).

With the printer's spooler on, an Epson answers **Printed** when it has accepted the page, and a cover opened, paper out or a power cut after that is not reported. Epson lists the spooler per printer, and none for the TM-m30III series, so what the TM-m30III-H reports for a cover opened or paper out has not been tried: judge on the paper. The `result_code` of the job holds the printer's own words. An Epson that has been switched off reads **Offline** about 4 minutes after its last poll. Look at **Last seen**.

Do not queue a page for a printer added by its paper width before it has connected: until then its maker is not known, and the page is made for a Star. If the printer turns out to be an Epson, that page ends **Failed** with the reason `rendered_for_other_vendor`. Nothing prints. Send it again, and it is made for the Epson.

## Step 4: check the line width

An Epson reports no line width. A printer added by its paper width prints for the default of its paper, 48 columns on 80 mm and 35 on 58 mm, until its width has been checked on paper. Until then its page says **Check the line width**. An owner or a developer checks it in the dashboard:

1. Press **Print calibration sheet**, then **Print the sheet**. The sheet comes within about one poll interval.
2. Look at the sheet. It has two rulers, each with a code of four symbols under it. A ruler that stays on one line fits. One that is cut off, or that runs on to a second line, is too long.
3. Type the code under the longest ruler that fits, and press **Confirm**. The dialog says **Confirmed**, and the printer's **Profile** row then reads that it was confirmed on paper with a code.
4. Press **Test print** and look at the paper.

The code is a typo guard and not proof that anyone stands at the printer: a code that is not one of the sheet's two is refused and sets no profile, and anyone who sees the sheet can read it. A sheet that is not printed within 20 minutes expires, and a code works for 30 minutes and 5 tries, so print a new sheet when one runs out. See [Profiles and print options](/printers/profiles#check-the-line-width-of-an-epson-on-paper).

The sheet and its code are in the dashboard. With the API, set the profile yourself once the printer has connected: `PATCH /v1/printers/{printer}` with a `profile`, for example `epson-80mm-42`. A printer added with its maker and profile named needs no sheet.

## If it does not connect

"Never connected" looks the same for several causes, so go in this order:

1. **The maker.** `GET /v1/printers/{printer}` must show `vendor: "epson"`. If it shows `star` and `vendor_source` is `explicit`, the printer was added as a Star: delete it and add it again. If `vendor_source` is `default`, the printer was added by its paper width and has not connected yet: go through the causes below. If it has connected and still reads `star` with `detection` `pending`, delete it and add it again with `"vendor": "epson"`.
2. **The URL.** Compare it character by character with the one you were given, with no trailing slash and no spaces. Open it in a browser on the same network: the [check page](/concepts/printer-url#check-a-url-in-a-browser) tells you whether its form is right.
3. **The settings.** Server Direct Print and ePOS-Print enabled, the settings applied and the printer restarted.
4. **The clock.** A wrong date makes every certificate invalid.
5. **The certificate.** The full test page was printed through production, which is HTTPS only, so the printer connected to the certificate Tillcast presents (issued by Amazon). Whether **Server Authentication** was enabled, so that the printer checked that certificate, has not been checked, and neither has the TLS version it used. If the printer does not trust the certificate, the fix is made on the printer: import **Amazon Root CA 1** from [Amazon Trust Services](https://www.amazontrust.com/repository/) where Web Config takes CA certificates. As a last resort, for a test with test data only, set **Server Authentication** to Disable. The printer then accepts any certificate, so set it back to Enable afterwards.

If the page stays **Queued** while the printer is **Online**, an older job is ahead of it: the oldest is served first. A page handed to the printer with no result ends **Failed** with the reason `result_missing` after about two minutes. See [Troubleshooting](/printers/troubleshooting).

## When you are done testing

Clear the Server1 URL in Web Config and apply, or switch the printer off, before you delete the printer or the location. A printer that keeps polling an address you have deleted keeps asking every few seconds.