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

# Changelog

## October 26, 2026

## Every new organization has a free trial on real printers

* **Free trial.** An organization can use a free trial on real printers, one per organization and per person: 1 month, 250 printed jobs in total, no card to start ([terms of service](https://tillcast.com/legal/terms/), section 8a).
* **On paper.** The trial prints on real paper. Every job printed in the trial ends with a line that reads `Test print` and `tillcast.com`, and the line cannot be switched off.
* **Pages.** [API authentication](/api/authentication) and [Build with an agent](/build-with-an-agent) said that a free trial was planned, with no date. They now say that it is there.

## An Epson prints in the multilingual encoding unless you set another

* **What changed.** A job for an Epson printer whose `print_options` name no `encoding` is now written in `multilingual`, not in code page 852. `multilingual` writes each character in the first of five code pages that has it, so the Polish and the Swedish letters, the euro sign and the typographic quotes and dashes print in one text, and a job with them no longer carries a `character_unmappable` warning for them. This holds for all five Epson profiles. The profile ids are the same, and a job that was queued before keeps the bytes it was rendered with.
* **What you see.** Text of ASCII characters prints as before, and its bytes lose the `ESC t 18` that code page 852 wrote in front of each run of text. A job with letters outside ASCII is a few bytes longer for each change of code page. The footer of a trial prints as `Test print · tillcast.com` with the middle dot on an Epson, where it had a hyphen.
* **Unchanged.** A printer with an `encoding` of its own, `cp852` included, is rendered as before. The Star profiles are as they were, the `star-starprnt-cp852-80mm` and `-58mm` profiles too. `print_options.encoding` takes the same names, and the API version is still `2026-10-01`.
* **Not checked on a device.** This was checked on paper on one Epson TM-m30III-H, with a Swedish and a Polish sample. Other Epson models, the full test page and the middle dot of the trial footer have not been seen on paper with it. On a model where a letter prints wrong, set `encoding` to the code page that model has.
* **Pages.** [Profiles and print options](/printers/profiles), [Troubleshooting](/printers/troubleshooting) and [Set up an Epson printer](/printers/epson-setup) say how it works.

## October 25, 2026

## The rule for API versions is written down

* **No breaking changes within a version date.** From the day the page was published, a version date does not change in a way that breaks code written for it. A breaking change comes only with a new version date. See [Versioning](/api/versioning).
* **What counts.** Removing or renaming a field, changing a type, a new required field or parameter, and a different status code or error code for a case that already has one are breaking. A new optional field, a new endpoint and new detail in an error are not.
* **Notice and old versions.** A breaking change to the REST API `/v1` takes effect no earlier than 6 months after Tillcast e-mails the owners of the organization, and a version date that a newer one has replaced stays available for at least 12 months. This is section 17 of the Terms of service. It covers only `/v1`: the MCP server is not covered, and a change of a limit or the enforcement of a rate limit keeps a notice of 30 days.
* **Why.** The job body changed from an object to an array of blocks on 2026-10-16 under the same date. The page says so, and no longer says that the API can change under a date.
* **Unchanged.** The API is as it was, and the current version is still `2026-10-01`.

## October 24, 2026

## A printer can be added by its paper width

* **`paper_width` on create.** `POST /v1/locations/{location}/printers` takes an optional `paper_width`, `58mm` or `80mm`. Sent with none of `vendor`, `profile`, `print_options` and `allowed_mac`, the printer reads `star` until its first connection. Then Tillcast reads the maker from what the printer sends, and a Star's width from what it reports. Sent with a `vendor`, `paper_width` is only recorded and chooses the default profile of that paper. Left out, nothing changes. See [Add a printer by its paper width](/printers/profiles#add-a-printer-by-its-paper-width).
* **Four fields on the printer.** `vendor_source`, `profile_source`, `paper_width` and `detection` say where the maker and the profile come from, the paper the printer was added for and what is left to settle. They are plain strings, in the answer for one printer and not in a list. A printer added before, or without `paper_width`, reads `explicit`, `explicit`, `null` and `done`.
* **`409 printer_not_identified`.** Until the maker of a printer added by its paper width is known, `PATCH /v1/printers/{printer}` is refused when it names `profile`, `print_options` or `allowed_mac`, or turns `welcome_print` on. The name, the `client_reference_id` and `welcome_print: false` go through.
* **A new reason for a failed job.** A page queued before the first connection of a printer added by its paper width is made for a Star. If the printer turns out to be an Epson, the job ends `failed` with the reason `rendered_for_other_vendor`, and nothing prints. Send it again.
* **In the dashboard.** **Add printer** asks for a name and the paper width. The maker, the profile, the allowed device and the print options are under **Advanced**. An Epson's line width is checked on paper: its page has **Print calibration sheet**, and you type the code under the longest ruler that stays on one line. The code is a typo guard and not proof that anyone stands at the printer.
* **Unchanged.** A create without `paper_width` works as it did, and a printer added with a maker named, or before this change, is never detected. The API version is still `2026-10-01`, and the fields and the error are additions.
* **SDKs.** The published packages are as they were and have no `paper_width` field. The call works with any HTTP client.
* **Not checked on a device.** Recognising a maker from its first connection, reading a Star's print area and the calibration sheet have not been checked on a device.
* **Pages.** The [Quickstart](/quickstart), [Provision a venue from your software](/provision-a-venue), [Profiles and print options](/printers/profiles), [Set up an Epson printer](/printers/epson-setup), [Set up a Star printer](/printers/star-setup), the [Printer setup checklist](/printers/setup-checklist), [First connection](/printers/first-connection), [Troubleshooting](/printers/troubleshooting) and [Errors](/api/errors) say how it works.

## October 21, 2026

## The MCP server is announced: connect an AI assistant with an API key

* **New page: [Connect an AI assistant (MCP)](/connect-an-ai-assistant).** Tillcast runs an MCP server at `https://api.tillcast.com/mcp`. An AI assistant that can send an `Authorization` header connects with an API key as the bearer token and gets 28 tools for customers, locations, printers and jobs, and `preview_document`, which draws a receipt without printing it. A key is shown only the tools its scopes allow, so a key with the Read only preset sees 10 tools and cannot print. The page has the setup for Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code, Zed and Claude custom connectors, says which of them Tillcast tried and which follow the vendor's documentation only, and lists the scopes to give, the safety notes and the troubleshooting.
* **Not yet.** OAuth sign-in for the MCP server is planned and not available, so an assistant that offers only OAuth sign-in, such as ChatGPT, cannot connect today. See the [roadmap](/roadmap).
* **Unchanged.** The REST API, the API reference and the SDKs are as they were. The contract does not list the MCP tools: the tools describe themselves to the client. A key prints on real paper, and there is still no test mode.
* **Agents.** [Build with an agent](/build-with-an-agent), the `AGENTS.md` snippet and the note at the top of every Markdown page now name the MCP server and tell an agent not to connect to it or call its tools unless the owner asked.
* **Update 2026-10-25.** Tillcast has no test mode.

## October 19, 2026

## The dashboard has two test buttons

* **Test print** on a printer's page now queues the **short** test page: a few lines and a cut, to check the address, the printer and the paper.
* **Full test page** is a second button. It queues the long page (about 80 cm of paper) with every barcode type, QR code and image.
* The API is as it was: `POST /v1/printers/{printer}/test-print` queues the short page, and `?page=full` queues the long one. See [First connection](/printers/first-connection).

## Partners, retries and testing: new page and corrections

* **New page: [Provision a venue from your software](/provision-a-venue).** For a software vendor that sets printers up for its own customers: a customer, a location and a printer through the API, the key and scope of each step, your own ids, safe retries, what to do when the answer that holds the printer URL is lost, handing the URL to the venue, and the first test page.
* **SDKs.** Both packages call the live API unless you set `baseUrl` (TypeScript) or `base_url` (Python), without `/v1`. They retry an answer of `408`, `429` or `5xx` (Python also `409`) and wait for `Retry-After` inside the call, and they do not retry a timeout or a dropped connection: retry that yourself with the same `Idempotency-Key` and body. See [SDKs](/getting-started/sdks) and [Create a print job](/create-a-print-job#retry-safely). The READMEs of the packages say so from the next version.
* **Corrections.** A `text` block of spaces or of a no-break space is accepted and prints a blank-looking line, and a document with no block, or one that prints nothing (blocks of only blank lines, a `text` block of nothing, a `receiptline` of only white space), is `422 document_empty`. A `cut` or a `rule` alone is accepted. A replay of a create returns the object as it is now. A job that the printer has taken stays `delivered` after `expires_at` until the printer confirms it, a full queue finishes it as `expired`, or its bytes are gone (from an hour after `expires_at`) and the printer's request for it ends it `failed` with `payload_unavailable`: such a job with `delivered_at` set may have printed. A job that never ends is deleted from 7 days after `expires_at`. A job past `expires_at` does not count against the 50 waiting jobs. The full test page is about 80 cm. See [Idempotency](/api/idempotency), [Jobs](/concepts/jobs) and [Errors](/api/errors).
* **Testing.** There is no safe way to test against the live API today: no test mode, no virtual printers, no webhooks and no preview call over HTTP. [Build with an agent](/build-with-an-agent) says what an agent does instead, and has a brief for an agent that integrates Tillcast into a point of sale.
* **Update 2026-10-25.** Tillcast has no virtual printers for customers and no test mode.

## October 18, 2026

## For agents: what exists and what does not

* **Roadmap.** The roadmap has a new part, "In development", for what is being built and is not available: a template language and stored templates, an MCP server for the API, and sign-in with Google. OAuth connections and connectors for Make, Zapier and n8n are listed as planned. Nothing in "In development" or "Planned" can be used, and none has a date. See the [roadmap](/roadmap).
* **Build with an agent.** The `AGENTS.md` snippet says that stored templates, a `template` or `data` field on a job, OAuth connectors, the API's own MCP server, webhooks and test mode do not exist and must not be coded against, and that the docs are the source of truth: check [llms.txt](https://docs.tillcast.com/llms.txt) before you code against a field. There is a new prompt that checks an integration against the docs. See [Build with an agent](/build-with-an-agent).
* **Welcome.** The first page names the call, the key and its scope, and the two ways to write the receipt (`document` as blocks, or `receiptline`).
* **Examples.** Every example that sends a different request has an idempotency key of its own, so two examples run one after the other do not meet `422 idempotency_key_reused`.
* **SDKs.** The TypeScript `err.requestId` reads the header `x-request-id`, which the API does not send, so it is `undefined`. Read `err.body.error.request_id`. See [SDKs](/getting-started/sdks).
* **Update 2026-10-25.** Tillcast has no test mode.

## October 17, 2026

## SDK READMEs and the job guide

* **A page for creating a job.** [Create a print job](/create-a-print-job) is the page to start from once you have an API key and a printer. It has the smallest request in cURL, TypeScript and Python, what each field means, the `201` answer, what happens next and how to read the job, retrying with an `Idempotency-Key` with a replay shown, the usual refusals including `422 document_invalid` and its `param`, receipts to copy as blocks and as ReceiptLine text, and the test print. The welcome page and the quickstart lead to it, and it is third in the navigation.
* **READMEs of the SDKs.** From version 0.2.1, the README of `@tillcast/sdk` and of `tillcast` leads with creating a print job: how to install the package, where to get an API key, the client with `token`, a receipt as blocks and as ReceiptLine text, the idempotency key, reading the job back with `jobs.get`, and how to read a refused document. The README of version 0.2.0 shows only the creation of a customer. See [SDKs](/getting-started/sdks).

## October 16, 2026

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

## October 15, 2026

## The Tillcast API is live

The Tillcast API, the dashboard and the status page are live, and these docs now describe them. The API reference is built from the real contract of the service. It lists the customer operations (customers, locations, printers, jobs, the test print and the organization) with their requests, answers and error codes.

* **API.** `https://api.tillcast.com/v1`, with restricted API keys and six scopes, `Idempotency-Key`, cursor pagination and the `Tillcast-Version` header. The current version is `2026-10-01`.
* **A job carries a ReceiptLine document.** Tillcast renders it into the commands of the printer's profile when it accepts the job, and lists what the renderer noticed in `warnings`. The new page [Receipt documents](/concepts/documents) explains the language and the escape rule for text of your own, with helpers for TypeScript and Python.
* **Printers.** Tillcast supports Star CloudPRNT and Epson Server Direct Print. New pages: [Set up an Epson printer](/printers/epson-setup) and [Profiles and print options](/printers/profiles). [Supported printers](/printers/supported-printers) lists example models and what has run on a device. [Set up a Star printer](/printers/star-setup) says what has been checked on a real printer and what has not.
* **Dashboard.** At [dashboard.tillcast.com](https://dashboard.tillcast.com), sign-up is open and a new organization is active at once. Owners and developers create API keys, customers, locations and printers, and print a test page.
* **Status page.** [status.tillcast.com](https://status.tillcast.com) shows printer connections, printing, the public API and the dashboard. See [Status and incidents](/status).
* **Quickstart.** It now takes you from sign-up to a printed receipt: an API key, a customer, a location, a printer, a job and its status.
* **Rewritten.** The pages that said the service was planned or in a pre-release phase now describe what is live. The rate limits, retention and suspension pages say what exists today.
* **Still planned.** Webhooks and events, test mode, an MCP server for the API and push to printers. They stay marked as planned. See the [roadmap](/roadmap).
* **SDKs:** the TypeScript and Python packages are generated from this contract. They are coming soon as pre-1.0 versions and are not published yet.
* **Update 2026-10-25.** Tillcast has no test mode.

## October 11, 2026

## Documentation: developer pages added

New pages for developers. Everything is marked as planned, because the API, the dashboard and the SDKs do not exist yet.

* **Quickstart** with the cURL calls of the planned API.
* **Using the API:** authentication and API keys with scopes, versioning, idempotency, errors, pagination, and rate limits and retention.
* **Phase 2, planned:** webhooks and events, and test mode.
* **Printers:** a printer setup checklist.
* **Status and incidents:** where the planned status page will be.
* **API reference:** a placeholder reference. The real contract replaces it when the API exists.
* **Build with an agent** lists what exists today: `llms.txt`, Markdown pages, the page actions and the docs MCP server.
* **Changed:** "API keys and versions" is now [Authentication and API keys](/api/authentication) and [Versioning](/api/versioning).
* **Update 2026-10-25.** Tillcast has no test mode.

## October 10, 2026

## Documentation site created

The Tillcast documentation site is online. It is a pre-release site that describes the planned service: concepts, printers, security and data, and a roadmap. The API, the dashboard and the SDKs do not exist yet.