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

# Concepts overview

> The Tillcast hierarchy of organization, customer, location, printer and job, and how a printer connects.

## The Tillcast hierarchy

Everything in Tillcast sits in one chain: organization, customer, location, printer, job.

| Level        | What it is                                                                                                                                                              | Example                      |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| Organization | The software vendor that uses Tillcast. Its people sign in to the dashboard, it owns API keys, and it has customers.                                                    | A property management system |
| Customer     | A company that uses the organization's software. It owns one or more locations. Its short code is the host of its printers' URLs.                                       | A hotel company              |
| Location     | One site of a customer. A location can be paused.                                                                                                                       | One hotel                    |
| Printer      | One physical printer, with a name and a maker, Star or Epson. It has its own secret in its URL. After it connects, Tillcast reads its brand and model from the printer. | "Reception left"             |
| Job          | One document to print. A job is created under a printer.                                                                                                                | A guest bill                 |

You can create customers, locations and printers in the dashboard or through the API. Anyone can create an organization in the dashboard, and it is active at once. See the [Quickstart](/quickstart), and [Provision a venue from your software](/provision-a-venue) for a vendor that sets printers up for its own customers.

Ids carry a prefix and an `object` field names the kind of object: `org_`, `loc_`, `prn_` and `job_`, each followed by a ULID. `key_` is the id of an API key record, never part of the key itself. The customer is the exception. Its id is `cus_` and an 8-character code, for example `cus_c3x9k2m3`, because people type the code into printers as part of the URL.

An object that belongs to another organization looks like a missing object, with the answer `404`. See [Security and data](/security#how-organizations-are-kept-apart).

## How a printer connects

A printer connects to Tillcast. Tillcast never connects to the printer.

1. You enter the [printer URL](/concepts/printer-url) in the printer's web settings. A Star printer takes it in its CloudPRNT settings, and an Epson in its Server Direct Print settings.
2. The printer sends a small request over HTTPS to that URL about every 5 seconds. This is a poll. The 5 second interval is the default.
3. If a job is waiting, the answer to the poll carries it, or says that one is ready. The printer downloads the job, prints it and confirms.
4. Tillcast marks the job as printed. See [Jobs](/concepts/jobs).

Because the printer makes every request, the venue network only has to allow outgoing HTTPS. There is no VPN, no port forwarding and no local server. A new job can wait up to about one poll interval before the printer asks for it.

Tillcast supports the two technologies below. Your documents are the same for both, and the printer's [profile](/printers/profiles) decides which commands Tillcast makes of them.

| Technology           | Maker | Where you enter the URL                                                             |
| -------------------- | ----- | ----------------------------------------------------------------------------------- |
| CloudPRNT, HTTP mode | Star  | The printer's CloudPRNT settings. See [Set up a Star printer](/printers/star-setup) |
| Server Direct Print  | Epson | The printer's Web Config. See [Set up an Epson printer](/printers/epson-setup)      |

Push to printers, so that a job prints without waiting for a poll, is planned and not built. Printers that cannot poll a server, such as those of other makers, will need Tillcast Bridge, a small device in the venue for printers on its network. It is planned and not available. See [Supported printers](/printers/supported-printers) and the [roadmap](/roadmap).

## Status of a printer

The printer answers show where a printer stands.

* **`status`** is one of `never_connected`, `online`, `offline`, `wrong_host`, `mac_mismatch`, `customer_suspended` and `location_suspended`. The last two say that the customer or the location is paused, and so is the printer.
* **`last_seen_at`** is when the printer last polled. It is in the answer for a single printer and is written at most once a minute.
* **`status_code`** is the last status code the printer sent, for example `200 OK` or, from a Star, `410 Out of paper` and `420 Cover open`.
* **`brand`**, **`model`** and **`mac`** are what the printer said about itself. They are claims of whoever polled with the URL, and they are `null` until the printer has connected. An Epson reports none of them.

> **A printer that stops polling reads offline**
>
> A printer that has connected and has not polled for about 4 minutes has the status `offline`, and `connection` reads `disconnected`. The status is worked out when you read the printer, from `last_seen_at`, so it appears 3 to 4 minutes after the last poll and goes at the printer's next poll. Keep a printer's polling interval at 60 seconds or less.

The printer object also has the fields `connection` and `condition`. `connection` is `disconnected` when the status is `offline`; the checks behind `condition` are not all built, so use `status_code` for that.

## Where to go next

* [Receipt documents](/concepts/documents)
* [Printer URL](/concepts/printer-url)
* [Jobs](/concepts/jobs)
* [Suspension and pause](/concepts/suspension)
* [Authentication and API keys](/api/authentication)
* [Provision a venue from your software](/provision-a-venue)
* [Quickstart](/quickstart)