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

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