Quickstart
From sign-up to a first receipt: an API key, a customer, a location, a printer and a job.
This page takes you from nothing to a printed receipt. You need:
- A Star or an Epson printer that polls a server by itself, on a network with outgoing HTTPS, and a computer on the same network. See Supported printers.
- A terminal with
curl. The examples usejqto pick ids out of the answers. Without it, copy the ids from the answers by hand.
Everything in steps 3 and 4 can also be done in the dashboard. Each step says how.
Already have an API key and a printer? Go straight to Create a print job, the page on the call your software makes for every receipt. If your software will make customers, locations and printers by itself for its own customers, read Provision a venue from your software after this page.
Sign up and create an organization
Go to dashboard.tillcast.com and sign up with your e-mail address and a password. Tillcast e-mails a code to confirm the address. Then sign in and create an organization: the business whose people sign in to the dashboard. You become its owner, and it is active at once. Nothing has to be approved first.
You can add an authenticator app or a passkey to your account, and invite colleagues, from the dashboard.
Create an API key
In the dashboard open API keys, and press Create key.
- Give the key a label, for example the name of the integration, and choose the preset Setup and printing. It holds all six scopes, enough to create a customer, a location and a printer and to print. Press Next. For production, create a second key with the Printing preset. A key that only sets things up needs the Installer preset, and it cannot print, so a test page needs a key with
jobs:write. See Authentication and API keys and Provision a venue from your software. - Check the scopes, choose that the key works for the whole organization, and choose an expiry. Press Create key.
- Confirm with the six-digit code that Tillcast e-mails to you. Creating a key always needs this extra step.
- Copy the key. It is shown once, and only its last four characters are kept in the list.
Keep it in an environment variable, and check that it works:
The answer names your organization and lists the scopes of the key. If it says 401 invalid_api_key, the key was copied wrongly. The Tillcast-Version header is optional and pins the behavior you tested. See Versioning.
Add a customer and a location
A customer is a company that uses your software, for example a hotel company. A location is one site of a customer, for example one hotel. A printer belongs to a location. The id of a customer is cus_ and its code, and the code becomes the host of its printers’ URLs.
In the dashboard, press Create customer on Customers, then open the customer and press Add location. With the API:
The Idempotency-Key makes a repeat of the same call return the same object, so a retry cannot create a second one. See Idempotency.
Add a printer and get its URL
In the dashboard, open the location and press Add printer, type a name and choose the Paper width: Tillcast reads the maker when the printer connects. With the API, choose the tab of your printer.
The printer URL is returned once, in the answer that adds the printer. It holds the printer’s secret, so treat it like a password. The command below saves the answer to a file that only you can read. Run it once: the same call again answers url: null, and the same key with another body is refused, so use only the tab of your printer.
Star or Epson, 80 mm
Star or Epson, 58 mm
Epson, maker named
With paper_width and nothing that names the maker, Tillcast reads the maker when the printer first connects, and a Star’s width from what it reports. Until then the answer below says "vendor": "star", "vendor_source": "default" and "detection": "pending". An Epson’s line width is checked on paper afterwards, see Set up an Epson printer.
To name the maker instead, as the last tab does, send "vendor": "epson": a printer is a Star unless you say so. Then choose the profile of the printer’s paper, for example a 58 mm profile for a 58 mm printer. A named maker cannot be changed afterwards, and nothing is detected. Without a profile, a Star gets star-starprnt-utf8-80mm and an Epson gets epson-80mm-48, both for 80 mm paper.
If the file holds an error instead of a printer, fix the cause, delete the file and run the call again: a refused create leaves its Idempotency-Key free. Otherwise read the id and the URL from the file:
Enter the URL in the printer
Type the URL into the printer, then restart it. The URL is the only credential the printer has. Leave the username and password fields empty.
- Star: open
http://<printer-ip>/in a browser on the same network, open the CloudPRNT settings, enable CloudPRNT in HTTP mode, paste the URL into Server URL, set the polling time to 5 seconds, and Save & Restart. Full steps: Set up a Star printer. - Epson: open the printer’s Web Config, then TM-i Settings, Server Direct Print. Enable it, paste the URL into Server1, URL, set Interval(s) to 5, check that ePOS-Print reads Enable, and Apply & Restart. Full steps: Set up an Epson printer.
Delete the file that holds the URL when you are done: rm printer.json.
Within a poll or two after the restart the printer connects. Check it:
The status turns from never_connected to online, and a Star shows its brand and model within a poll or two. A printer added by its paper width shows its maker in vendor, and detection goes from pending to done, or to undetected for a Star whose report cannot be used. An Epson then needs its line width checked: its page in the dashboard says Check the line width. A Star that connects for the first time prints a welcome receipt with the names of your location and printer, so you see at once that the URL was typed correctly. An Epson prints none. If nothing happens, open the URL in a browser for a check of its form, and see Troubleshooting.
Once the status reads online, you can see paper from either maker: press Test print on the printer’s page in the dashboard, or call the API. Do not do it before the printer is online: on a Star it would take the place of the welcome receipt, and a printer whose maker is not known yet is sent a page made for a Star. See First connection.
Send a job
A job carries a receipt document: an array of blocks, such as text, a table, a QR code. Tillcast renders it for the printer’s profile when it accepts the job. The Idempotency-Key stops a retry from queuing a second job. Use a new key for each new receipt. A Star printer can still print a job twice, see Jobs.
TypeScript
Python
cURL
Install the package first: npm install @tillcast/sdk for TypeScript, or pip install tillcast for Python (see SDKs). The blocks need version 0.2.0 or later: 0.1.1 sends the earlier form of the document, which the API no longer accepts. To run the TypeScript tab, use Node 22.18 or later (Node 24 does too), which runs TypeScript directly: save it as send.mts and run node send.mts. The cURL tab needs jq only if you want the id of the job.
The answer is 201 with the job. It is queued, and warnings lists anything the renderer noticed in the document. Text of your own, such as a name or an item, goes into a block as it is: nothing in a block is markup. See Receipt documents.
This step is the short version. Create a print job has the fields, the retries and the refusals.
Read the status of the job
The printer takes the job within about one poll interval, 5 seconds by default, then prints it and confirms. The state changes from queued to delivered to printed. See Jobs.
TypeScript
Python
cURL
If the status is failed, reason and result_code say why. With its spooler on, printed for an Epson means that the printer accepted the page: the paper decides. Do not poll faster than you need. Webhooks, which tell you without polling, are planned and not built yet.
Where to go next
- Create jobs from your software: Create a print job.
- Write real receipts: Receipt documents, with every kind of block.
- Handle failure: Errors, Idempotency and Jobs.
- Install an SDK for TypeScript or Python: SDKs.
- Set the paper width and the character set: Profiles and print options.
- Browse every operation in the API reference.
Not available yet
Webhooks and events, push to printers and stored templates do not exist yet: do not write code that depends on them. The SDKs for TypeScript and Python do exist, as pre-1.0 versions. The MCP server exists too, for an AI assistant that connects with a key. See SDKs, Connect an AI assistant (MCP) and the roadmap.