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 printandtillcast.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_optionsname noencodingis now written inmultilingual, not in code page 852.multilingualwrites 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 acharacter_unmappablewarning 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 18that 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 asTest print · tillcast.comwith the middle dot on an Epson, where it had a hyphen. - Unchanged. A printer with an
encodingof its own,cp852included, is rendered as before. The Star profiles are as they were, thestar-starprnt-cp852-80mmand-58mmprofiles too.print_options.encodingtakes the same names, and the API version is still2026-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
encodingto 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
/v1takes 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_widthon create.POST /v1/locations/{location}/printerstakes an optionalpaper_width,58mmor80mm. Sent with none ofvendor,profile,print_optionsandallowed_mac, the printer readsstaruntil its first connection. Then Tillcast reads the maker from what the printer sends, and a Star’s width from what it reports. Sent with avendor,paper_widthis 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_widthanddetectionsay 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 withoutpaper_width, readsexplicit,explicit,nullanddone. 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 namesprofile,print_optionsorallowed_mac, or turnswelcome_printon. The name, theclient_reference_idandwelcome_print: falsego 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
failedwith the reasonrendered_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_widthworks as it did, and a printer added with a maker named, or before this change, is never detected. The API version is still2026-10-01, and the fields and the error are additions. - SDKs. The published packages are as they were and have no
paper_widthfield. 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 anAuthorizationheader connects with an API key as the bearer token and gets 28 tools for customers, locations, printers and jobs, andpreview_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.mdsnippet 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-printqueues the short page, and?page=fullqueues 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) orbase_url(Python), without/v1. They retry an answer of408,429or5xx(Python also409) and wait forRetry-Afterinside the call, and they do not retry a timeout or a dropped connection: retry that yourself with the sameIdempotency-Keyand body. See SDKs and Create a print job. The READMEs of the packages say so from the next version. - Corrections. A
textblock 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, atextblock of nothing, areceiptlineof only white space), is422 document_empty. Acutor arulealone is accepted. A replay of a create returns the object as it is now. A job that the printer has taken staysdeliveredafterexpires_atuntil the printer confirms it, a full queue finishes it asexpired, or its bytes are gone (from an hour afterexpires_at) and the printer’s request for it ends itfailedwithpayload_unavailable: such a job withdelivered_atset may have printed. A job that never ends is deleted from 7 days afterexpires_at. A job pastexpires_atdoes 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.mdsnippet says that stored templates, atemplateordatafield 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 (
documentas blocks, orreceiptline). - 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.requestIdreads the headerx-request-id, which the API does not send, so it isundefined. Readerr.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
201answer, what happens next and how to read the job, retrying with anIdempotency-Keywith a replay shown, the usual refusals including422 document_invalidand itsparam, 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/sdkand oftillcastleads with creating a print job: how to install the package, where to get an API key, the client withtoken, a receipt as blocks and as ReceiptLine text, the idempotency key, reading the job back withjobs.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.
documentis an array of blocks. Each block is one visible unit and says itstype:text,row,table,rule,cut,feed,barcode,qrorimage. 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.receiptlineis 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 wasdocument.contentasreceiptline.- Exactly one of the two. A job with both
documentandreceiptline, or with neither, is422 document_invalid. A job with no document at all was400 parameter_missingbefore. - The earlier body is gone.
{"document": {"type": "receiptline", "content": "..."}}is400 parameter_invalid, and the message says where the text goes now. Where an error saiddocument.contentinparam, it now saysreceiptline. - A new error for blocks. A block that cannot be printed as it is said is
422 document_invalid, andparamis the path of the first problem, such asdocument[3].rows[1][0].size. - SDKs. Version 0.1.1 of
@tillcast/sdkandtillcastsends the earlier object, and the API refuses it. Version 0.2.0 sends the array. In Python the blocks, and alsoprint_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.mdsnippet 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 replacesexternal_idon customers and locations andreferenceon jobs, which are now refused with400 parameter_unknown. See Your own IDs.- The
external_id_takenerror is gone. A value is never refused for being used already. - Old request shape removed. A job body with
media_typeandpayload_base64is refused like any unknown field. A job carries adocument. - 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/sdkand the Python packagetillcastare published as pre-1.0 versions (0.1.1). See SDKs. The npm packagetillcastwithout 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 theTillcast-Versionheader. The current version is2026-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.