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

## The job body is an array of blocks

**This is a breaking change of the body of a job, made under the same API version, `2026-10-01`.** There is no alias and no migration period: the earlier body is refused. SDK 0.2.0 follows and sends the new body.

* **`document` is an array of blocks.** Each block is one visible unit and says its `type`: `text`, `row`, `table`, `rule`, `cut`, `feed`, `barcode`, `qr` or `image`. Tillcast renders the document for the printer's profile, as before. The text of a block prints as it is written, so there is nothing to escape. See [Receipt documents](/concepts/documents).
* **`receiptline` is the field for ReceiptLine text.** It is for documents written for other ReceiptLine tools. The escape rule applies to this text only. To keep a document as it is, send the text that was `document.content` as `receiptline`.
* **Exactly one of the two.** A job with both `document` and `receiptline`, or with neither, is `422 document_invalid`. A job with no document at all was `400 parameter_missing` before.
* **The earlier body is gone.** `{"document": {"type": "receiptline", "content": "..."}}` is `400 parameter_invalid`, and the message says where the text goes now. Where an error said `document.content` in `param`, it now says `receiptline`.
* **A new error for blocks.** A block that cannot be printed as it is said is `422 document_invalid`, and `param` is the path of the first problem, such as `document[3].rows[1][0].size`.
* **SDKs.** Version 0.1.1 of `@tillcast/sdk` and `tillcast` sends the earlier object, and the API refuses it. Version 0.2.0 sends the array. In Python the blocks, and also `print_options`, are written as plain dicts, and a type checker no longer accepts the model classes of 0.1.1 in a request. See [SDKs](/getting-started/sdks).
* **Pages.** The examples of the [Quickstart](/quickstart), [Jobs](/concepts/jobs), [Idempotency](/api/idempotency), [Integrate a point of sale](/integrate-a-pos) and [SDKs](/getting-started/sdks) send blocks, and so does the `AGENTS.md` snippet of [Build with an agent](/build-with-an-agent).

## One field for your own IDs, and a full test page

* **`client_reference_id`.** Customers, locations, printers and jobs carry the id they have in your own system in one field with one name. It is not unique, and every list can search by it. It replaces `external_id` on customers and locations and `reference` on jobs, which are now refused with `400 parameter_unknown`. See [Your own IDs](/concepts/client-reference-id).
* **The `external_id_taken` error is gone.** A value is never refused for being used already.
* **Old request shape removed.** A job body with `media_type` and `payload_base64` is refused like any unknown field. A job carries a `document`.
* **Full test page.** **Test print** in the dashboard queues a long page, about 80 cm of paper, with every barcode type, QR code and image. With the API, call the test print with `?page=full`. See [First connection](/printers/first-connection#the-full-test-page).
* **New page.** [Integrate a point of sale](/integrate-a-pos) says what the code of a till or an order system needs.
* **SDKs.** The TypeScript package `@tillcast/sdk` and the Python package `tillcast` are published as pre-1.0 versions (0.1.1). See [SDKs](/getting-started/sdks). The npm package `tillcast` without a scope is empty and points to `@tillcast/sdk`.