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

# Printer URL

> The Tillcast printer URL format, what its customer code and secret mean, how to treat it as a password, and how to move or replace a printer.

## Printer URL format

Each printer gets one URL. The values below are made up.

```text wordWrap
https://<customer code>.print.tillcast.com/<secret>
```

```text wordWrap
https://c3x9k2m3.print.tillcast.com/r4twh8nca3bx5dfn
```

* You enter it in one field of the printer's settings: the **Server URL** of a Star printer, or the **URL** of the Server1 setting of an Epson. See [Set up a Star printer](/printers/star-setup) and [Set up an Epson printer](/printers/epson-setup).
* There is no username and no password. The secret in the URL is the credential. Leave the username and password fields of the printer empty.
* The URL is `https` only. Tillcast listens on no plain HTTP port, so a printer set to `http://` fails to connect before it sends anything.
* The URL has no trailing slash. A path with more than one part, a trailing slash or a dot is not a printer URL.

You get the URL when you add the printer, in the dashboard or in the answer of the API. See the [Quickstart](/quickstart).

## The two parts of the URL

| Part          | Where                       | Length        | What it does                                                                             |
| ------------- | --------------------------- | ------------- | ---------------------------------------------------------------------------------------- |
| Customer code | The first label of the host | 8 characters  | Names the customer. All printers of a customer share it. It always starts with a letter. |
| Secret        | The path                    | 16 characters | Identifies one printer. It is random.                                                    |

Both parts use only the digits 2 to 9 and the lowercase letters except `i`, `l` and `o`, so no character can be read two ways. Upper and lower case are treated the same.

The last character of each part is a check symbol. A typo in a single character, or a swap of two neighbouring characters, makes the check fail, and Tillcast rejects the request without looking anything up. See [Troubleshooting](/printers/troubleshooting).

The customer code is not secret. It appears in DNS and in the host name, and it grants nothing without the secret. The id of the customer in the API is `cus_` and the code.

## Treat the URL as a password

The secret is the only credential a printer has. Anyone who has the whole URL can poll as that printer, download the receipts waiting for it and confirm them.

* Tillcast keeps only a hash of the secret. The full URL is shown once: when the printer is added, when its secret is rotated, and when a move to another customer changes its host. A replayed request that added the printer answers `url: null`.
* If the URL is lost or leaks, rotate the secret with `POST /v1/printers/{printer}/rotate-secret`, which needs the `printers:write` scope. The answer holds the new URL, and the old URL stops working at once. In the dashboard, an owner or a developer presses **Rotate secret** on the printer's page, and the new URL is shown once.
* Do not put the URL in logs, tickets, chat messages or source code. Tillcast never writes it to its own logs: the path of a request is logged only as `/<secret>`.
* The printer's own web page shows the URL. Change the printer's web admin password if it is still the factory default. See [Set up a Star printer](/printers/star-setup).

## Check a URL in a browser

Open the printer URL in a browser on the same network. You get a small page, not a receipt. It checks the form of both parts and says one of these:

* The form of the URL is right. The page cannot tell whether the secret exists, so it cannot be used to test guesses. If the printer still does not connect, compare the URL with the one you were given.
* There is a typo in the customer code, or in the secret.
* The URL is not active.
* The address has no secret after the host.

The page also has a box where you can type a URL to check its symbols. It does this in your browser, with no request.

## Allow only one device (optional)

By default any device that holds the URL works, and nothing ties the URL to the first device that connects. A printer can name the one device that is allowed to use it, by its MAC address, in the field `allowed_mac`. In the dashboard it is the optional **Allowed device (MAC address)** field of the Edit printer dialog, and of the Add printer dialog under **Advanced** once a maker is chosen there. A printer added by its paper width takes an allowed device only after it has connected and its maker is known.

This is a safeguard for one address and not authentication. A MAC address is printed on the label of the printer, and its first three bytes name the maker. The secret in the URL stays the credential.

* A MAC address is twelve hexadecimal digits, with `:` or `-` between the pairs or none. `00:11:62:00:00:0a` and `00116200000a` are the same device. It cannot be all zeros, all `f` or a group address.
* Set it when you add the printer, or later with `PATCH /v1/printers/{printer}` and `printers:write`. `{"allowed_mac": null}` removes it.
* With a device named, the MAC the device reports must be that one. A request that reports none is refused too. The refusal is a bare `403`, the same as for a wrong URL.
* It needs a firmware that reports its MAC address. Only firmware 5.2 of a Star mC-Print3 has been seen to do it. If the `mac` of the printer reads `null` after it has connected, the printer does not report one, and it would be refused as soon as a device is named. An Epson reports no MAC at all, so a device cannot be named for it.

To avoid locking a printer out, connect it first without an allowed device. Read the `mac` that `GET /v1/printers/{printer}` shows, compare it with the label and the self-test print, and only then set it. Some models print the Wi-Fi MAC on the label and report the Ethernet one: name the one the printer reports. A mistyped MAC stops the printer behind a bare `403`. The printer then shows the status `mac_mismatch` and `reported_mac`, which can take up to an hour to appear.

A change takes effect for a device that the new value leaves out within about a second. A device that it names, or any device after `null`, is let in about 30 seconds later, plus the printer's poll interval.

## Moving and replacing printers

* **Move inside a customer:** `POST /v1/printers/{printer}/move` with the new `location`. The URL does not change, and nothing changes on the printer. Jobs never move with a printer, so a printer with waiting jobs is refused with `409 pending_jobs`, unless you send `cancel_pending_jobs: true`. A receipt for one hotel never prints in another.
* **Move to another customer:** the host changes, so the printer gets a new URL, which the answer shows once. Enter it on the printer again. The old URL stops working at once. A Star prints the [welcome receipt](/printers/first-connection) again.
* **Move to another organization:** this is not a move. A location must belong to your organization. Delete the printer and add a new one.
* **Replace the hardware:** with no allowed device, a new printer that holds the same URL just works, and brand and model follow the new device within a day. With an allowed device, change `allowed_mac` to the MAC of the new printer, or remove it. Nothing has to be released. A replaced printer behind the same URL prints no new welcome receipt.

Moving a printer and changing or deleting a customer or a location are done with the API and a key. The dashboard can add a printer, edit its name, profile and allowed device, rotate its secret, delete it and print a test page.

## Own domain for printer URLs

Printer URLs can be on your own domain, for example `print.example.com`, as an extra on request. Tillcast sets the domain up for your organization, and the price is agreed individually: ask through the [contact page](https://tillcast.com/contact/). No API call sets a domain up. Once one is active for your organization, a printer made with `domain` left out gets its URL on it, and the `domain` of the printer says which one it has. The host of the URL is still `<code>.<domain>`, with the code Tillcast gives the customer.