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

# Integrate a point of sale

> How a point of sale sends a print job: key, printer, idempotency, your own order id, and what to do when something goes wrong.

> **The API prints on real paper**
>
> A key prints on real printers. Use a key made for the integration, keep it in an environment variable and never write it into code or logs.

This page is for the code that sits in your point of sale or order system. Set the printers up first with the [quickstart](/quickstart), or, if your software sets printers up for its own customers, with [Provision a venue from your software](/provision-a-venue). The examples use the [SDKs](/getting-started/sdks) (`npm install @tillcast/sdk`, `pip install tillcast`); every call is also a plain HTTP request, shown as cURL.

## What you need

* An API key with the scope `jobs:write`, `jobs:read` if you read job states and `printers:read` if you look printers up. Make it in the dashboard, under **API keys**.
* The id of each printer (`prn_...`) that the integration prints to. A till, a kitchen and a bar are three printers with three ids. Put your own name for each in its [`client_reference_id`](/concepts/client-reference-id) and look the printers up with `GET /v1/printers?client_reference_id=kitchen-1`.

## Send a job

One job is one document for one printer, and [Create a print job](/create-a-print-job) goes through the call field by field. The document is an array of [blocks](/concepts/documents): text, tables, rules, QR codes, barcodes and images. Text that is not yours, such as a guest name or an item name, goes into a block as it is. Nothing in a block is markup, so there is nothing to escape.

#### TypeScript

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

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

const job = await client.jobs.create({
  printer: "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
  "Idempotency-Key": "order-4714-bill",
  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"],
        { type: "rule" },
        [{ text: "Total", bold: true }, { text: "3.40", bold: true }],
      ],
    },
  ],
  client_reference_id: "order-4714",
  expires_in: 600,
});
```

#### Python

```python
import os

from tillcast import Tillcast

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

job = client.jobs.create(
    printer="prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
    idempotency_key="order-4714-bill",
    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"],
                {"type": "rule"},
                [{"text": "Total", "bold": True}, {"text": "3.40", "bold": True}],
            ],
        },
    ],
    client_reference_id="order-4714",
    expires_in=600,
)
```

#### cURL

```bash wordWrap
curl https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/jobs \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Idempotency-Key: order-4714-bill" \
  -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"], {"type": "rule"}, [{"text": "Total", "bold": true}, {"text": "3.40", "bold": true}]]}
    ],
    "client_reference_id": "order-4714",
    "expires_in": 600
  }'
```

* **`Idempotency-Key`**: one key per print you intend, for example the order number and the kind of paper (`order-4714-bill`, `order-4714-kitchen`). A retry with the same key answers the first job and prints nothing more. Keys are remembered for 24 hours.
* **`client_reference_id`**: your order number. It is not unique and Tillcast never refuses it. Use it to find the jobs of an order later.
* **`expires_in`**: how many seconds a printer may be offered the job. A kitchen ticket that is an hour late is worse than none, so choose a short time.

The answer is `201` with the job, and its `warnings` list what the renderer could not print as written. A printer that is off or offline takes the job when it is back, if the job has not expired.

## Delivery and duplicates

A Star printer confirms a job after it printed, and a lost confirmation can make it ask for the job again. An Epson is not offered a job again, but a job that ends `failed` with `result_missing` may have printed. Make a second print harmless: do not make the paper the proof that something happened. If a job must not print twice, check its state with `GET /v1/jobs/{job}` before you send it again.

## Find a job again

#### TypeScript

```ts
const found = await client.jobs.list({
  client_reference_id: "order-4714",
  printer: "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
});
```

#### Python

```python
found = client.jobs.list(
    client_reference_id="order-4714",
    printer="prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
)
```

#### cURL

```bash wordWrap
curl "https://api.tillcast.com/v1/jobs?client_reference_id=order-4714&printer=prn_01M44X7TQ0A9R2H5J8K1M4N7P0" \
  -H "Authorization: Bearer $TILLCAST_API_KEY"
```

A job is `queued`, `delivered`, `printed`, `failed`, `expired` or `cancelled`. See [Jobs](/concepts/jobs) for what each means and for the reasons a job fails. With its spooler on, an Epson reports `printed` when it has accepted the page, so a cover opened after that is not reported.

## When something goes wrong

* **`429`**: `rate_limited`, or `queue_full` when the printer already has 50 jobs waiting. Wait for the time in the `Retry-After` header (30 seconds for `queue_full`) and send the same request again with the same `Idempotency-Key`. Do not loop on `queue_full`: the queue empties as the printer prints, as you cancel jobs and as jobs pass their `expires_at` (24 hours by default), so a printer that is off keeps refusing until jobs in its queue expire. After a few tries, tell a person.
* **`409`**: the printer, its location or its customer is suspended or paused. Read the error `code`. See [Errors](/api/errors) and [Suspension and pause](/concepts/suspension).
* **`400`, `413` or `422`**: your request is wrong, for example a block that cannot be printed as it is said (`document_invalid`, and `param` is the path of the block), a document that is too large or one that carries a printer command. What the printer's profile cannot print as written is not refused: it prints, and `warnings` says what changed.
* **No answer, a `5xx`, a timeout**: send the same request again with the same `Idempotency-Key` and the same body. You get the first job, never a second one. The SDKs do this for a `5xx` and not for a timeout or a dropped connection, so keep your own record of the print before you call and retry from it. See [Retry safely](/create-a-print-job#retry-safely) and the table in [Errors](/api/errors#what-to-do).

## Check the printer first

Press **Full test page** on the printer's page in the dashboard before you go live. It queues a long page with every barcode type, QR code and image the printer can be asked for, about 80 cm of paper. Print it on the printer you will use. The other button, **Test print**, queues a short page that only checks the address, the printer and the paper.

An agent that writes this integration should read [Build with an agent](/build-with-an-agent) first.