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

# SDKs

> Install the Tillcast SDK for TypeScript (@tillcast/sdk) or Python (tillcast) and send a first job.

The SDKs are generated from the [API contract](/api-reference). They are **pre-1.0**: method names can still change before 1.0, so pin the version you use. Both packages are MIT licensed. Anything the SDK does not cover, the HTTP API does.

| Language   | Package                                                        | Install                     |
| ---------- | -------------------------------------------------------------- | --------------------------- |
| TypeScript | [`@tillcast/sdk`](https://www.npmjs.com/package/@tillcast/sdk) | `npm install @tillcast/sdk` |
| Python     | [`tillcast`](https://pypi.org/project/tillcast/)               | `pip install tillcast`      |

The old npm package named `tillcast` is empty. It only points to `@tillcast/sdk`.

> **The API prints on real paper**
>
> A key prints on real printers, and a client built with only a key calls the live API. Keep the key in an environment variable, never in code, and test with the printer you mean to print on. See [Which server the SDK calls](#which-server-the-sdk-calls).

## Send a job

#### 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": "order-4713-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-4713",
});
console.log(job.id, job.status, job.warnings);
```

#### Python

```python
import os

from tillcast import Tillcast

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

job = client.jobs.create(
    printer=os.environ["TILLCAST_PRINTER_ID"],
    idempotency_key="order-4713-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-4713",
)
print(job.id, job.status, job.warnings)
```

An `Idempotency-Key` makes a retry safe: the same key answers the first job and prints nothing more. See [Create a print job](/create-a-print-job) for the whole call, [Idempotency](/api/idempotency) and [Integrate a point of sale](/integrate-a-pos).

The `document` is an array of [blocks](/concepts/documents). To send ReceiptLine text, use the field `receiptline` instead of `document`, with a string.

## Which server the SDK calls

Both packages call the **live API**, `https://api.tillcast.com`, unless you say otherwise, and a job they create prints on a real printer. Tillcast has no test server: there is no sandbox and no staging API.

To send the calls to another address, for example a stand-in server of your own in automated tests, set the base URL when you build the client: `baseUrl` in TypeScript and `base_url` in Python. Write the address without `/v1`, because the SDK adds the path of every call. With `/v1` at the end, every call is `404 route_not_found`.

#### TypeScript

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

function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is not set`);
  return value;
}

const client = new TillcastClient({
  token: requireEnv("TILLCAST_API_KEY"),
  baseUrl: requireEnv("TILLCAST_BASE_URL"),
});
```

#### Python

```python
import os

from tillcast import Tillcast

client = Tillcast(
    token=os.environ["TILLCAST_API_KEY"],
    base_url=os.environ["TILLCAST_BASE_URL"],
)
```

A missing base URL is not an error. `baseUrl: undefined` in TypeScript and `base_url=None` in Python both mean the live API, so a client in a test that forgot the setting prints on paper. Read the address as above, so that a missing setting stops the program, and set `TILLCAST_BASE_URL=https://api.tillcast.com` in production. In unit tests, do not build a client at all: pass your code a fake client of your own. Never call the live API from a test or from an agent unless the owner of the key gave you the key and named the printer.

## The README of the packages

The README is the first page of a package on npm and PyPI. From version 0.2.1, the README of both packages leads with creating a print job:

1. How to install the package, where to get an API key and how to build the client with `token`.
2. **Create a print job**: a short receipt as blocks, with a centred title, a table, a rule and a total, and the same receipt as ReceiptLine text in `receiptline`.
3. **Retry safely**: the idempotency key, which is `idempotency_key` in Python and the property `"Idempotency-Key"` in TypeScript, and how to see a replay.
4. **Read a job** back with `jobs.get` and its status, and where the printer id comes from.
5. **A refused document**: `422 document_invalid`, and how to read the `param` of the error.

The rest of the README is what Fern generates for every SDK: the environments, the async client of Python, retries and timeouts. Versions 0.2.0 and earlier have only that generated README, and its one example is `customers.create`, which is not a job. The code of a package does not change with its README. The page [Create a print job](/create-a-print-job) has the same call with cURL and more.

## Version 0.2.0 and blocks

The job body changed on 2026-10-16: `document` was an object, `{"type": "receiptline", "content": "..."}`, and is now an array of blocks. Version **0.1.1** of both packages sends the object, and the API answers `400 parameter_invalid`. Version **0.2.0** and later send the array. Update the package and change the call. See the [changelog](/changelog).

* **TypeScript.** `type` picks the kind of block, and the editor offers the fields of that kind. A field that a kind does not have, a misspelled field and a value of the wrong kind are errors of the compiler. The type of a block is `Tillcast.Block`: give a document that you build in a variable this type, or the compiler reads `type: "text"` as a string.
* **Python.** The parameters of a request that are objects are dicts (TypedDicts), so write the blocks as plain dicts, as above, and a type checker like pyright checks them. This also holds for `print_options`: the model classes of 0.1.1, such as `PrintOptions(...)`, are not accepted by a type checker in a request. The type of a block is `BlockParams`, for a function that returns a document. The answers are still objects: `job.id`, `job.warnings`.
* **Neither or both.** `document` and `receiptline` are both optional in the types, so neither the compiler nor the type checker can see that a call has neither or both. The API answers `422 document_invalid`.

## Notes

* The names of the fields are the names of the API (`client_reference_id`, `expires_in`, and in a barcode `module_width`). In Python the header is the argument `idempotency_key`; in TypeScript it is the property `"Idempotency-Key"`.
* Errors are exceptions that carry the status and the error body. A `422` is `Tillcast.UnprocessableEntityError` in TypeScript and `UnprocessableEntityError` in Python, and its `body.error` has the `code`, the `param` and the `request_id`. See [Errors](/api/errors). The TypeScript error also has a property `requestId`, but it reads the header `x-request-id`, and the API sends `Request-Id`, so it is `undefined`. Read `err.body.error.request_id` (the same value) in both languages, or `err.rawResponse.headers.get("request-id")` in TypeScript. An error with no answer behind it, such as a timeout or a refused connection, has no request id.
* Both packages retry a request twice, with a growing wait, when Tillcast **answers** `408`, `429` or a `5xx` (Python also `409`). They wait for the `Retry-After` of the answer, up to 60 seconds, so a `queue_full` (`Retry-After: 30`) can hold one call for about a minute. They do **not** retry a timeout or a dropped connection, the cases where the job may already exist: send the same request again yourself, with the same `Idempotency-Key` and body. Set `maxRetries` (TypeScript) or `max_retries` (Python) to 0 to turn the waits off. See [Retry safely](/create-a-print-job#retry-safely).
* Both packages call the live API, `https://api.tillcast.com`, by default. Set `baseUrl` (TypeScript) or `base_url` (Python), without `/v1`, to call another address. See [Which server the SDK calls](#which-server-the-sdk-calls).