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

# Quickstart

> Sign up, create an API key, add a customer, a location and a Star or Epson printer, send a first job and read its status.

This page takes you from nothing to a printed receipt. You need:

* A Star or an Epson printer that polls a server by itself, on a network with outgoing HTTPS, and a computer on the same network. See [Supported printers](/printers/supported-printers).
* A terminal with `curl`. The examples use `jq` to pick ids out of the answers. Without it, copy the ids from the answers by hand.

Everything in steps 3 and 4 can also be done in the dashboard. Each step says how.

Already have an API key and a printer? Go straight to [Create a print job](/create-a-print-job), the page on the call your software makes for every receipt. If your software will make customers, locations and printers by itself for its own customers, read [Provision a venue from your software](/provision-a-venue) after this page.

#### Sign up and create an organization

Go to [dashboard.tillcast.com](https://dashboard.tillcast.com) and sign up with your e-mail address and a password. Tillcast e-mails a code to confirm the address. Then sign in and create an organization: the business whose people sign in to the dashboard. You become its owner, and it is active at once. Nothing has to be approved first.

You can add an authenticator app or a passkey to your account, and invite colleagues, from the dashboard.

#### Create an API key

In the dashboard open **API keys**, and press **Create key**.

1. Give the key a label, for example the name of the integration, and choose the preset **Setup and printing**. It holds all six scopes, enough to create a customer, a location and a printer and to print. Press **Next**. For production, create a second key with the **Printing** preset. A key that only sets things up needs the **Installer** preset, and it cannot print, so a test page needs a key with `jobs:write`. See [Authentication and API keys](/api/authentication) and [Provision a venue from your software](/provision-a-venue).
2. Check the scopes, choose that the key works for the whole organization, and choose an expiry. Press **Create key**.
3. Confirm with the six-digit code that Tillcast e-mails to you. Creating a key always needs this extra step.
4. Copy the key. It is shown once, and only its last four characters are kept in the list.

Keep it in an environment variable, and check that it works:

```bash wordWrap
export API=https://api.tillcast.com
export TILLCAST_API_KEY="tc_rk_live_..."

curl $API/v1/organizations/me \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01"
```

The answer names your organization and lists the scopes of the key. If it says `401 invalid_api_key`, the key was copied wrongly. The `Tillcast-Version` header is optional and pins the behavior you tested. See [Versioning](/api/versioning).

#### Add a customer and a location

A customer is a company that uses your software, for example a hotel company. A location is one site of a customer, for example one hotel. A printer belongs to a location. The id of a customer is `cus_` and its code, and the code becomes the host of its printers' URLs.

In the dashboard, press **Create customer** on **Customers**, then open the customer and press **Add location**. With the API:

```bash wordWrap
CUSTOMER=$(curl -s $API/v1/customers \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: quickstart-customer-1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example Hotels"}' | jq -r .id)

LOCATION=$(curl -s $API/v1/customers/$CUSTOMER/locations \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: quickstart-location-1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Hotel Example"}' | jq -r .id)

echo $CUSTOMER $LOCATION
```

The `Idempotency-Key` makes a repeat of the same call return the same object, so a retry cannot create a second one. See [Idempotency](/api/idempotency).

#### Add a printer and get its URL

In the dashboard, open the location and press **Add printer**, type a name and choose the **Paper width**: Tillcast reads the maker when the printer connects. With the API, choose the tab of your printer.

The printer URL is returned **once**, in the answer that adds the printer. It holds the printer's secret, so treat it like a password. The command below saves the answer to a file that only you can read. Run it once: the same call again answers `url: null`, and the same key with another body is refused, so use only the tab of your printer.

#### Star or Epson, 80 mm

```bash wordWrap
curl -s $API/v1/locations/$LOCATION/printers \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: quickstart-printer-paper80-1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Reception left", "paper_width": "80mm"}' > printer.json
chmod 600 printer.json
```

#### Star or Epson, 58 mm

```bash wordWrap
curl -s $API/v1/locations/$LOCATION/printers \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: quickstart-printer-paper58-1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Reception left", "paper_width": "58mm"}' > printer.json
chmod 600 printer.json
```

#### Epson, maker named

```bash wordWrap
curl -s $API/v1/locations/$LOCATION/printers \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: quickstart-printer-epson-1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Reception left", "vendor": "epson", "profile": "epson-80mm-48"}' > printer.json
chmod 600 printer.json
```

With `paper_width` and nothing that names the maker, Tillcast reads the maker when the printer first connects, and a Star's width from what it reports. Until then the answer below says `"vendor": "star"`, `"vendor_source": "default"` and `"detection": "pending"`. An Epson's line width is checked on paper afterwards, see [Set up an Epson printer](/printers/epson-setup#step-4-check-the-line-width).

To name the maker instead, as the last tab does, send `"vendor": "epson"`: a printer is a Star unless you say so. Then choose the [profile](/printers/profiles) of the printer's paper, for example a 58 mm profile for a 58 mm printer. A named maker cannot be changed afterwards, and nothing is detected. Without a `profile`, a Star gets `star-starprnt-utf8-80mm` and an Epson gets `epson-80mm-48`, both for 80 mm paper.

```json wordWrap
{
  "id": "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
  "object": "printer",
  "customer": "cus_c3x9k2m3",
  "location": "loc_01M42YMFP03Q1P9N7M5K3H1G0F",
  "name": "Reception left",
  "client_reference_id": null,
  "vendor": "star",
  "vendor_source": "default",
  "brand": null,
  "model": null,
  "mode": "live",
  "status": "never_connected",
  "connection": "never_connected",
  "condition": [],
  "status_code": null,
  "mac": null,
  "allowed_mac": null,
  "pending_jobs": 0,
  "auth_error_at": null,
  "reported_mac": null,
  "profile": "star-starprnt-utf8-80mm",
  "profile_source": "default",
  "paper_width": "80mm",
  "detection": "pending",
  "welcome_print": true,
  "created_at": "2026-10-16T09:25:00Z",
  "url": "https://c3x9k2m3.print.tillcast.com/r4twh8nca3bx5dfn"
}
```

If the file holds an error instead of a printer, fix the cause, delete the file and run the call again: a refused create leaves its `Idempotency-Key` free. Otherwise read the id and the URL from the file:

```bash wordWrap
PRINTER=$(jq -r .id printer.json)
export TILLCAST_PRINTER_ID=$PRINTER
jq -r .url printer.json
```

#### Enter the URL in the printer

Type the URL into the printer, then restart it. The URL is the only credential the printer has. Leave the username and password fields empty.

* **Star:** open `http://<printer-ip>/` in a browser on the same network, open the CloudPRNT settings, enable CloudPRNT in HTTP mode, paste the URL into **Server URL**, set the polling time to 5 seconds, and **Save & Restart**. Full steps: [Set up a Star printer](/printers/star-setup).
* **Epson:** open the printer's Web Config, then **TM-i Settings**, **Server Direct Print**. Enable it, paste the URL into **Server1**, **URL**, set **Interval(s)** to 5, check that **ePOS-Print** reads Enable, and **Apply & Restart**. Full steps: [Set up an Epson printer](/printers/epson-setup).

Delete the file that holds the URL when you are done: `rm printer.json`.

Within a poll or two after the restart the printer connects. Check it:

```bash wordWrap
curl -s $API/v1/printers/$PRINTER \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01" | jq '{status, last_seen_at, vendor, detection, brand, model}'
```

The `status` turns from `never_connected` to `online`, and a Star shows its brand and model within a poll or two. A printer added by its paper width shows its maker in `vendor`, and `detection` goes from `pending` to `done`, or to `undetected` for a Star whose report cannot be used. An Epson then needs its line width checked: its page in the dashboard says **Check the line width**. A Star that connects for the first time prints a [welcome receipt](/printers/first-connection) with the names of your location and printer, so you see at once that the URL was typed correctly. An Epson prints none. If nothing happens, open the URL in a browser for a check of its form, and see [Troubleshooting](/printers/troubleshooting).

Once the status reads `online`, you can see paper from either maker: press **Test print** on the printer's page in the dashboard, or call the API. Do not do it before the printer is online: on a Star it would take the place of the welcome receipt, and a printer whose maker is not known yet is sent a page made for a Star. See [First connection](/printers/first-connection#test-print).

```bash wordWrap
curl -s -X POST $API/v1/printers/$PRINTER/test-print \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: quickstart-test-1"
```

#### Send a job

A job carries a [receipt document](/concepts/documents): an array of blocks, such as text, a table, a QR code. Tillcast renders it for the printer's profile when it accepts the job. The `Idempotency-Key` stops a retry from queuing a second job. Use a new key for each new receipt. A Star printer can still print a job twice, see [Jobs](/concepts/jobs#delivery-and-duplicates).

#### TypeScript

```ts
import { TillcastClient } from "@tillcast/sdk";

const client = new TillcastClient({ token: process.env.TILLCAST_API_KEY! });

const job = await client.jobs.create({
  printer: process.env.TILLCAST_PRINTER_ID!,
  "Idempotency-Key": `hello-${Date.now()}`,
  document: [
    { type: "text", text: "Harbour Cafe", align: "center", bold: true, size: 2 },
    { type: "text", text: "Table 7", align: "center" },
    {
      type: "table",
      columns: ["*", { width: 9, align: "right" }],
      rows: [
        ["Flat white", "3.40"],
        ["Lemon cake", "4.20"],
        { type: "rule" },
        [{ text: "Total", bold: true }, { text: "7.60", bold: true }],
      ],
    },
  ],
  client_reference_id: "hello-1",
});
console.log(job.id, job.status, job.warnings);
```

#### Python

```python
import os
import time

from tillcast import Tillcast

client = Tillcast(token=os.environ["TILLCAST_API_KEY"])

job = client.jobs.create(
    printer=os.environ["TILLCAST_PRINTER_ID"],
    idempotency_key=f"hello-{int(time.time())}",
    document=[
        {"type": "text", "text": "Harbour Cafe", "align": "center", "bold": True, "size": 2},
        {"type": "text", "text": "Table 7", "align": "center"},
        {
            "type": "table",
            "columns": ["*", {"width": 9, "align": "right"}],
            "rows": [
                ["Flat white", "3.40"],
                ["Lemon cake", "4.20"],
                {"type": "rule"},
                [{"text": "Total", "bold": True}, {"text": "7.60", "bold": True}],
            ],
        },
    ],
    client_reference_id="hello-1",
)
print(job.id, job.status, job.warnings)
```

#### cURL

```bash wordWrap
JOB=$(curl -s $API/v1/printers/$PRINTER/jobs \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: hello-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
    "document": [
      {"type": "text", "text": "Harbour Cafe", "align": "center", "bold": true, "size": 2},
      {"type": "text", "text": "Table 7", "align": "center"},
      {"type": "table", "columns": ["*", {"width": 9, "align": "right"}],
       "rows": [["Flat white", "3.40"], ["Lemon cake", "4.20"], {"type": "rule"},
                [{"text": "Total", "bold": true}, {"text": "7.60", "bold": true}]]}
    ],
    "client_reference_id": "hello-1"
  }' | jq -r .id)

echo $JOB
```

Install the package first: `npm install @tillcast/sdk` for TypeScript, or `pip install tillcast` for Python (see [SDKs](/getting-started/sdks)). The blocks need version 0.2.0 or later: 0.1.1 sends the earlier form of the document, which the API no longer accepts. To run the TypeScript tab, use Node 22.18 or later (Node 24 does too), which runs TypeScript directly: save it as `send.mts` and run `node send.mts`. The cURL tab needs `jq` only if you want the id of the job.

The answer is `201` with the job. It is `queued`, and `warnings` lists anything the renderer noticed in the document. Text of your own, such as a name or an item, goes into a block as it is: nothing in a block is markup. See [Receipt documents](/concepts/documents).

This step is the short version. [Create a print job](/create-a-print-job) has the fields, the retries and the refusals.

#### Read the status of the job

The printer takes the job within about one poll interval, 5 seconds by default, then prints it and confirms. The state changes from `queued` to `delivered` to `printed`. See [Jobs](/concepts/jobs).

#### TypeScript

```ts
const status = await client.jobs.get({ job: job.id });
console.log(status.status, status.reason, status.result_code, status.warnings);
```

#### Python

```python
status = client.jobs.get(job.id)
print(status.status, status.reason, status.result_code, status.warnings)
```

#### cURL

```bash wordWrap
curl -s $API/v1/jobs/$JOB \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01" | jq '{status, reason, result_code, warnings}'
```

If the status is `failed`, `reason` and `result_code` say why. With its spooler on, `printed` for an Epson means that the printer accepted the page: the paper decides. Do not poll faster than you need. Webhooks, which tell you without polling, are planned and not built yet.

## Where to go next

* Create jobs from your software: [Create a print job](/create-a-print-job).
* Write real receipts: [Receipt documents](/concepts/documents), with every kind of block.
* Handle failure: [Errors](/api/errors), [Idempotency](/api/idempotency) and [Jobs](/concepts/jobs).
* Install an SDK for TypeScript or Python: [SDKs](/getting-started/sdks).
* Set the paper width and the character set: [Profiles and print options](/printers/profiles).
* Browse every operation in the [API reference](/api-reference).

## Not available yet

Webhooks and events, push to printers and stored templates do not exist yet: do not write code that depends on them. The SDKs for TypeScript and Python do exist, as pre-1.0 versions. The MCP server exists too, for an AI assistant that connects with a key. See [SDKs](/getting-started/sdks), [Connect an AI assistant (MCP)](/connect-an-ai-assistant) and the [roadmap](/roadmap).