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

# First connection

> The welcome receipt a Star printer prints when it first connects to Tillcast, and how to print a test page on a Star or an Epson printer.

## What the welcome receipt is

When a Star printer connects with a new URL for the first time, it prints a short welcome receipt. The installer sees on the spot that the URL was typed correctly and belongs to the right location. The values below are made up.

```text
------------------------------------------------
                Printer connected
------------------------------------------------
Location:     Hotel Example
Printer:      Reception left
Organization: Example Software
Model:        Star mC-Print3
Firmware:     5.2
Time (UTC):   2026-10-09 12:05

This printer is ready.
```

An Epson prints no welcome receipt. An Epson added with its maker named is added with the receipt off, and its `welcome_print` reads `false`. A printer added by its paper width reads `welcome_print` `true` until it first connects, unless it was added with the receipt off, and if it turns out to be an Epson, that first connection switches the receipt off. Use the test print below to see that an Epson works.

## What the welcome receipt shows

* The location name and the printer name. They show at once whether the printer got the URL of the right location.
* The organization's name.
* The printer model and firmware, when the printer has reported them.
* The time of the first connection, in UTC. It is not the local time of the location.

The receipt never shows the printer URL, the secret or anything else that would let someone poll as this printer. The labels are in English. Names print as given: Tillcast escapes them, so a name cannot change the layout of the receipt.

A few lines of the organization's own text, such as a support phone number, are designed to print under "This printer is ready". Setting that text is not built yet, so the receipt has none today.

## When the welcome receipt prints

* On the first connection of a Star printer.
* After every new URL: when the printer is added, when its secret is rotated, and when it moves to another customer.
* Not after a move inside a customer, because the URL does not change.
* Not when a job is already waiting at the first connection. Printing that job confirms the connection anyway, and a test print queued before the first connection takes the place of the welcome receipt.
* Not when a new device connects behind the same URL. A replaced printer prints no new welcome receipt.
* A Star added by its paper width is asked about its paper first, so its receipt follows its answer: a little later than for a Star added with its maker named.

It is on by default. A printer can turn it off for itself: send `"welcome_print": false` when you add the printer or with `PATCH /v1/printers/{printer}`, or clear the checkbox under **Advanced** in the Add printer dialog of the dashboard. A switch for all the printers of an organization is not built yet.

The welcome job expires after 1 hour, so a printer that was out of paper does not print "connected" the next day. See [Jobs](/concepts/jobs).

## Test print

A test print queues one test page for a printer, to see that the address, the printer and the paper work. It works for a Star and for an Epson.

* In the dashboard, press **Test print** on the printer's page: it queues the short page that the rest of this section describes. The second button, **Full test page**, queues the [full test page](#the-full-test-page), a long page (about 80 cm of paper) that shows what the printer can print. An owner or a developer sees the buttons.
* With the API, call `POST /v1/printers/{printer}/test-print` with a key that has the `jobs:write` scope. The call takes no body. Without `page=full` it queues the short page that the rest of this section describes.

```bash wordWrap
curl -X POST https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Idempotency-Key: reception-test-1"
```

The answer is `201` with a job, as for any job. Its `kind` is `test`, and it carries the `profile`, the `transport` and the `warnings` of its render. The printer prints it the next time it polls. Then:

* A test print is never billed and does not count as a print of yours.
* It is offered to the printer for one hour only, so a page does not print the next morning.
* A printer takes at most 5 test prints in any minute and 3 waiting at a time. The next is `429 rate_limited` with a `Retry-After` header. The limit is per printer, so a page, a script and a second person share it. It stops a loop or a double click and is not a quota.
* It waits in the printer's queue of 50 like any job, and a suspended customer or a paused location refuses it.
* A printer added by its paper width has no known maker before its first connection, so a test print queued then is made for a Star. If the printer turns out to be an Epson, the page ends `failed` with the reason `rendered_for_other_vendor` and nothing prints. Press **Test print** after the first connection.

The page is a ReceiptLine document that is rendered for the printer's own profile. It has a heading with the name of your organization and the words `test print` (for an organization called Harbour Hotel, `Harbour Hotel test print`; a long name takes more than one line), the printer's name, the time in UTC, a table of three columns with lines, one line in each type style, and the cut. This is its text view at 48 columns. In the text view, double width letters are spaced out, and bold, underline and inverse are not visible. On paper, all of them are.

```text
------------------------------------------------
            Harbour Hotel test print
------------------------------------------------
Printer:    Reception left
Time (UTC): 2026-10-09 12:05:41
------------------------------------------------
+-----------------------------------+---+------+
|Item                               |Qty| Price|
+-----------------------------------+---+------+
|Espresso                           |  2|  7.00|
|Croissant                          |  1|  3.50|
|Orange juice                       |  1|  4.00|
+-----------------------------------+---+------+

Normal
Bold
D o u b l e   w i d t h
Double height
D o u b l e   W   a n d   H
Underlined
 Inverted
------------------------------------------------
```

A Star and an Epson print the same document, in the width, the character set and the commands of their profiles. The paper may differ in the details a model decides: the line spacing, the thickness of an underline, the feed before the cut, and the cut. Whether the page as a whole looks right on each model is still being checked. See [Supported printers](/printers/supported-printers).

### The full test page

To check that a printer can print everything, ask for the long page. Add `page=full` to the call:

```bash wordWrap
curl -X POST "https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full" \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Idempotency-Key: reception-test-full-1"
```

The page is about 80 cm of paper, and up to about 100 cm on a printer whose line feed is longer, so load a fresh roll. It shows every type style, a table, the Tillcast logo, a ruler for the width of the paper, a gray ramp, a density bar, 15 barcodes (every kind Tillcast prints) and 10 QR codes at every error level and four sizes. A barcode that is wider than the paper may not fit on narrow paper, and the page says so above it. Print it on a Star and on an Epson and compare the two.

* Without `page`, or with `page=basic`, you get the short page above. The idempotency key, the limits and the answer are the same for both.
* In solid black you may see a fine dotted pattern. It is the same on a Star and on an Epson. It comes from the way images are turned into dots and is normal. A whole missing line, or a frame with a missing edge, points at the printer or its settings.

## If nothing prints

See [Troubleshooting](/printers/troubleshooting). The welcome receipt does not print when the printer has turned it off, when the printer is an Epson, or when a job was already waiting.