Skip to navigation

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, 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 and 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, Troubleshooting and Set up an Epson printer say how it works.

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

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.
  • 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, Provision a venue from your software, Profiles and print options, Set up an Epson printer, Set up a Star printer, the Printer setup checklist, First connection, Troubleshooting and Errors say how it works.

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

  • New page: Connect an AI assistant (MCP). 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.
  • 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, 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.

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.

Partners, retries and testing: new page and corrections

  • New page: Provision a venue from your software. 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 and Create a print job. 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, Jobs and 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 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.

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.
  • 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 before you code against a field. There is a new prompt that checks an integration against the docs. See 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.
  • Update 2026-10-25. Tillcast has no test mode.

SDK READMEs and the job guide

  • A page for creating a 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.

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.
  • 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.
  • Pages. The examples of the Quickstart, Jobs, Idempotency, Integrate a point of sale and SDKs send blocks, and so does the AGENTS.md snippet of 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.
  • 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.
  • New page. Integrate a point of sale 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. The npm package tillcast without a scope is empty and points to @tillcast/sdk.

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 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 and Profiles and print options. Supported printers lists example models and what has run on a device. Set up a Star printer says what has been checked on a real printer and what has not.
  • Dashboard. At 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 shows printer connections, printing, the public API and the dashboard. See Status and incidents.
  • 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.
  • 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.

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 and Versioning.
  • Update 2026-10-25. Tillcast has no test mode.

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.