# Tillcast > Tillcast is a print API for receipt printers: your software sends a job and a printer in the venue prints it. ## Facts - Anyone can sign up for the dashboard. The price per printer per month is on the Pricing page and is graduated: each printer is charged at the price of its band. Above 100 printers: 5.25 EUR net per printer. A much more favourable individual quote is possible. - Free trial, one per organization and per person: many real printers, for 1 month from the first printer's first connection, with 250 printed jobs in total across all of them and no card to start. A printer that was part of a trial is not covered by another one. Each job printed in the trial ends with a line that reads "Test print" and tillcast.com. It prints on real paper, so run it only against a printer that a person made and named for you. Above 250 printed jobs, or after the month, jobs are refused until a card is added (the terms of service, section 8a). - One URL per printer; nothing to install at the venue. - Printers: Star (CloudPRNT) today. Tillcast supports Epson printers with Server Direct Print, and documents print on them. The full test page has been printed on an Epson TM-m30III-H. Planned (through Tillcast Bridge, a device for network printers, not available, no date): Citizen, Seiko Instruments, Fujitsu, other ESC/POS printers on a network. - API keys are restricted: each key has scopes such as jobs:write or printers:read. - Data is built to be stored in the EU (AWS eu-west-1, Ireland). - A job goes queued, delivered, printed; it can also fail, expire or be cancelled. Delivery to a Star printer is at least once. An Epson is not offered a job again once it has taken it: if its result is lost, the job is marked failed, although the page may have printed. - Documentation and API reference: https://docs.tillcast.com. Status page: https://status.tillcast.com. - Robots and AI agents are welcome to read this website: robots.txt allows everything, and the sitemap is https://tillcast.com/sitemap.xml. - SDKs, pre-1.0 (method names can still change before 1.0): TypeScript: npm install @tillcast/sdk; Python: pip install tillcast. - Show a receipt in your own web page without a printer: npm install @tillcast/preview (a React component and a function for any page; the renderer, @tillcast/html-render, comes with it). It draws blocks or ReceiptLine text as 80 mm paper in the browser, needs no API key and makes no request to Tillcast to draw. 0.x, Apache-2.0: pin the version. Guide: https://docs.tillcast.com/preview-a-receipt.md - Integrations: any tool or program that can send an HTTP request can create a print job with an API key today, with the SDKs or without them (see Create a print job below), and an AI assistant can use the MCP server with an API key (see MCP server below). - Operator: w3center.pl Daniel Miedzik, Poland. VAT PL7231586096. Contact: contact@tillcast.com. ## Create a print job - Endpoint: POST https://api.tillcast.com/v1/printers/{printer}/jobs ({printer} is the printer's id, such as prn_01J8ZQ4M7K). The body is JSON. - Authentication: the header "Authorization: Bearer ". The key needs the scope jobs:write. A person makes a key in the dashboard. Keep it in an environment variable, never in code or in a prompt. A key prints on real printers: send jobs only to a printer you were told to use. - Body: "document" is an array of blocks, the recommended way. "receiptline" is ReceiptLine text, an escape hatch for documents written for other ReceiptLine tools. Send exactly one of the two: both or neither is 422 document_invalid. The earlier body {"document": {"type": "receiptline", "content": "..."}} is refused with 400. - Block types: every block says its "type", one of text, row, table, rule, image, barcode, qr, cut, feed. The text of a block prints as it is written, so nothing in it is markup and it needs no escaping. An invalid block is 422 document_invalid, and "param" is the path of the problem, such as document[3].rows[1][0].size. - Example body: {"document":[{"type":"text","text":"Harbour Cafe","align":"center","size":2},{"type":"text","text":"Table 7","align":"center"},{"type":"table","columns":["*",{"width":9,"align":"right"}],"rows":[["Flat white","3.40"],["Lemon cake","4.20"],{"type":"rule"},["Total","7.60"]]}]} - A list of order lines: put one row per line in the "rows" of a table block, built from your own list in a loop, and send the whole receipt as one job. - Retries: send an Idempotency-Key header, 1 to 64 visible ASCII characters, one key for each print you intend (for example order-4711-bill). The same key with the same body returns the first job and prints nothing more (200, Idempotent-Replayed: true); the same key with a different body is an error (422). Keys are remembered for 24 hours. Delivery to a Star printer is at least once. The SDKs do not retry a timeout or a dropped connection, the cases where the job may already exist: record the print before the call and send the same request again yourself, with the same key and the same body. They wait for Retry-After inside the call (a full queue sends 30 seconds), so use maxRetries 0 (max_retries=0 in Python) in a request handler. - Answer: 201 with the job (id, status, warnings). Its status goes queued, delivered, printed; it can also end as failed, expired or cancelled. Read it with GET /v1/jobs/{job}. Find the jobs of your own order with GET /v1/jobs?client_reference_id=. - Not in the REST API: a job has no "template" or "data" field and there is no preview or dry-run call in the REST API (the MCP server has both; outside an MCP client, draw a receipt without printing it with the npm package @tillcast/preview or @tillcast/html-render, see the line about showing a receipt in your own web page). A field the API does not know, or a query parameter a route does not list, is refused with 400 parameter_unknown. - Details: https://docs.tillcast.com/create-a-print-job.md (the request, the answer, retries, refusals), https://docs.tillcast.com/concepts/documents.md (every block) and https://docs.tillcast.com/api/errors.md. The index of all documentation pages is https://docs.tillcast.com/llms.txt. The documentation is the source of truth: check it before you code against anything that is not described here. - SDKs, pre-1.0 (pin the version; 0.2.0 or later sends blocks): @tillcast/sdk for TypeScript (client.jobs.create({ printer, document: [...] })); tillcast for Python (client.jobs.create(printer=..., document=[...])). A plain HTTP client works as well. A client built with only a token calls the live API and prints on paper: pass baseUrl (TypeScript) or base_url (Python), without /v1, from a setting that must be present. ## Set up printers for your customers - A software vendor that sets printers up for its own customers makes them with the same API: POST /v1/customers, POST /v1/customers/{customer}/locations and POST /v1/locations/{location}/printers (scopes customers:read, customers:write, printers:read and printers:write, the Installer preset), then GET /v1/printers/{printer} for its status (it reads offline once the printer has not polled for about 4 minutes) and last_seen_at. Put your own id in client_reference_id, which is not unique: search before you create, and send a different Idempotency-Key for each create. - To have the maker (and a Star's paper width) read from the printer, send the paper in the create: "paper_width" ("58mm" or "80mm") and none of vendor, profile, print_options and allowed_mac. Until the printer has connected and been recognised, it reads vendor star, vendor_source default and detection pending (with paper_width and profile_source, in the create answer and in GET /v1/printers/{printer}), a PATCH that names profile, print_options or allowed_mac is 409 printer_not_identified, and a page sent meanwhile is made for a Star and fails with the reason rendered_for_other_vendor if the printer turns out not to be a Star. Without paper_width nothing is detected: the printer is a Star unless vendor says epson. - The printer's URL is a password and is shown only in an answer that issues it: the create (201), POST /v1/printers/{printer}/rotate-secret (scope printers:write; a new URL, the old one stops at once) and a move to another customer. A replay of the create shows url null, and a read or a list of printers never has it. A person makes the API keys in the dashboard and types the URL into the printer: the API cannot do either, and an agent must not try. - Details: https://docs.tillcast.com/provision-a-venue.md (the steps, the keys, a lost answer, handing the URL to the venue, the first test page). ## MCP server - Endpoint: https://api.tillcast.com/mcp. MCP over HTTP in the JSON-only form of Streamable HTTP: POST one JSON-RPC message, get one JSON answer. There is no event stream and no session (GET is 405), and a request that carries an Origin header is refused with 403. Protocol revisions 2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26. - Authentication: the header "Authorization: Bearer ", the same restricted key as the REST API. Its scopes and its limit to one customer decide what the tools may do. No key, or a wrong one, is 401. Make a key for the agent with only the scopes it needs, keep it in an environment variable and never paste it into a prompt. - Tools: 28, in these groups: the organization (1), customers (7), locations (7), printers (7), jobs and the test page (5), and preview_document (1), which shows a receipt without printing it. A key is shown only the tools its scopes allow (a key with the three read scopes sees 10). Keys, members and settings have no tool. - Care: create_job and test_print print on real paper at a customer's printer. Show the person a preview (preview_document, or create_job with dry_run: true) and print only what they agreed to. Send an idempotency_key with every create, as the tools require. create_printer and rotate_printer_secret return the printer's secret address: give a key printers:write only for a setup session. - Clients: Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code and Zed take a key as a header. Tillcast tried Claude Code and Gemini CLI against a local build of the server; the setup of the others follows the vendors' documentation and is not tested. The page below has the exact command or file for each. Do not add this server to a project's MCP configuration or call its tools unless the owner of the key asked you to: they act on the live account. - Not yet: OAuth sign-in for the MCP server is planned and not available, so an assistant that offers only OAuth sign-in (the custom MCP server form of ChatGPT, for example) cannot connect to it. Use a client that sends a key. - Details: https://docs.tillcast.com/connect-an-ai-assistant.md (setup for each client, the scopes to give, safety, troubleshooting). ## Not available yet - A template language and stored templates are in development and not available: do not code against them. - Webhooks are planned and do not exist. - There is no safe way to test against the live API: no webhooks and no preview call over HTTP (the MCP server's preview_document draws a receipt without printing it, and nothing else it does is a test; the npm packages @tillcast/preview and @tillcast/html-render draw one in your own code, with no call to Tillcast). Every key is live and a job prints on a real printer. An agent can write and type-check an integration, but running it needs a key and a printer that a person makes. In tests use a fake client of your own, and never call the live API, create a job or open a printer URL unless the owner gave you the key and named the printer. Creating a job and cancelling it at once is not a test: a printer takes a job within about 5 seconds. - Planned, with no date and not available: a template editor, OAuth connections and connectors for Make, Zapier and n8n, and OAuth sign-in for the MCP server. ## Pages - Each link is the page as plain Markdown. The page itself is at the same address without .md and with a closing slash (/pricing.md is /pricing/, /index.md is /). - [Tillcast](https://tillcast.com/index.md): Tillcast is a print API for receipt printers: your software sends a job and a printer in the venue prints it. - [Printers](https://tillcast.com/printers.md): Which receipt printers Tillcast supports: Star and Epson, more makers planned. What is tested, and how a printer connects. - [Security](https://tillcast.com/security.md): Where Tillcast stores data, how keys and printer URLs are protected, how long data is kept, and how to report a problem. - [Pricing](https://tillcast.com/pricing.md): A one-month trial on your real printers, up to 250 printed jobs. Production is paid per billable printer per month in EUR, net, graduated by band. - [Compare](https://tillcast.com/compare.md): How Tillcast compares with other cloud print services for receipt printers: price per printer, printers, API, customers and venues. - [Compared with StarIO.Online](https://tillcast.com/compare/stario-online.md): How Tillcast compares with StarIO.Online: price per printer, customers and venues, cutting a printer off, own domain, SDKs. - [Compared with Expedy](https://tillcast.com/compare/expedy.md): How Tillcast compares with Expedy: price per printer, prints included, job status, customers and venues, network and printers. - [Compared with ReceiptKit](https://tillcast.com/compare/receiptkit.md): How Tillcast compares with ReceiptKit: what the venue needs installed, price, prints included, templates and printers. - [Integrations](https://tillcast.com/integrations.md): Create print jobs from any tool that can send an HTTP request. An AI assistant can use the MCP server with a key. An editor and connectors are coming soon. - [Contact](https://tillcast.com/contact.md): Write to Tillcast by e-mail. Tillcast is operated by w3center.pl Daniel Miedzik, a sole proprietorship in Poland. - [Terms of service](https://tillcast.com/legal/terms.md): The terms of service (regulamin) for Tillcast: who may use it, prices and billing, suspension, liability and how the contract ends. - [Privacy notice](https://tillcast.com/legal/privacy.md): How Tillcast handles the personal data of website visitors and dashboard users: what, why, for how long, and your rights. - [Sub-processors](https://tillcast.com/legal/subprocessors.md): The providers Tillcast uses to run the service: what each one does, which data it handles and where that data is processed. - [Data processing agreement](https://tillcast.com/legal/dpa.md): The data processing agreement (GDPR Art. 28) between Tillcast and each organization, for the personal data in the jobs it prints. - [Blog](https://tillcast.com/blog.md): The Tillcast blog: how receipt printing from software works, guides for building with the API, and what is new in Tillcast. ## Blog - These posts are from Tillcast (https://tillcast.com/). Each link is the post as plain Markdown; the page of every post is at the address without .md. - [Atom feed](https://tillcast.com/blog/feed.xml): every post as it is published. - [Epson receipt printers and the cloud: the technologies they support](https://tillcast.com/blog/epson-printers-cloud-printing.md): ESC/POS, ePOS-Print, Server Direct Print and the ePOS SDKs: how Epson receipt printers are driven from software and the cloud, and what fits which job. (2026-11-09) - [ESC/POS, StarPRNT and ReceiptLine: printer languages and receipt formats](https://tillcast.com/blog/printer-languages-explained.md): What a receipt printer receives: bytes and command codes. ESC/POS and StarPRNT, code pages, QR codes and cutters, and ReceiptLine as an open text format. (2026-11-05) - [Star receipt printers and the cloud: the technologies they support](https://tillcast.com/blog/star-printers-cloud-printing.md): The main ways to send a print job to a Star Micronics receipt printer, from software and the cloud: CloudPRNT, command sets, SDKs, WebPRNT, PassPRNT, Star's hosted service, and what fits when. (2026-11-02) - [What is Epson Server Direct Print?](https://tillcast.com/blog/what-is-epson-server-direct-print.md): Server Direct Print lets an Epson receipt printer fetch its jobs from a web server. What a poll and its answer look like, what it needs, and where it stops. (2026-10-29) - [What is MQTT, and why do some receipt printers use it?](https://tillcast.com/blog/what-is-mqtt-for-printers.md): MQTT explained for developers: topics, QoS, retained messages, keep-alive and last will, and how Star CloudPRNT uses it to tell a printer a job is waiting. (2026-10-26) - [What is CloudPRNT? How Star printers fetch their print jobs](https://tillcast.com/blog/what-is-cloudprnt.md): CloudPRNT is Star Micronics' protocol for printers that fetch jobs from a server: the poll, fetch and confirm cycle, what is sent, what MQTT adds, the limits. (2026-10-23) - [Hotel and restaurant printing: five tickets worth automating](https://tillcast.com/blog/hotel-restaurant-tickets.md): A check-in card, guest bill, kitchen ticket, pick-up slip and housekeeping note: the trigger, the content, a Tillcast document and the pitfalls on paper. (2026-10-21) - [Preview a receipt in the browser with @tillcast/preview](https://tillcast.com/blog/design-receipt-preview-browser.md): Draw a receipt in the browser with @tillcast/preview: blocks or ReceiptLine in, a picture of 80 mm or 58 mm paper out, with no API key and no request to draw. (2026-10-21) - [How a cloud receipt printer gets its jobs](https://tillcast.com/blog/how-cloud-printers-get-jobs.md): A receipt printer cannot be called, so it asks a server for work. How Star CloudPRNT and Epson Server Direct Print do it, and what that means for retries. (2026-10-21) - [Print your first receipt with one API call](https://tillcast.com/blog/print-your-first-receipt.md): Send a receipt to a cloud printer with one API call, in curl, TypeScript or Python: a test print, a first document, job statuses, safe retries and errors. (2026-10-21)