Five tickets are worth automating in a hotel or a restaurant: the check-in card, the guest bill, the kitchen ticket, the order pick-up slip and the housekeeping note. Each one starts with an event your PMS or POS already knows about, and each one is a short document you can send to a printer with one API call. Below, for every ticket, you get what triggers it, what goes on it, a small Tillcast document you can send as it is, and what goes wrong on paper.
Each document is an array of blocks, the document of POST /v1/printers/{printer}/jobs. They are valid, they are accepted for an 80 mm printer and for a 58 mm printer, and the renderer has nothing to warn about on either. Every receipt below is drawn from its own document, on 80 mm paper (48 characters a line) and on 58 mm paper (32): choose the JSON tab to copy it. If you have not sent a job yet, the first post shows the calls.
1. The check-in card
Trigger: the reservation is marked as checked in.
What goes on it: the hotel, the guest’s name, the room, the dates, the breakfast hours and a QR code for the guest Wi-Fi. The guest keeps this card, so it should look like one.
Pitfalls. The QR code holds the network name and password in the usual WIFI: format, and a text that is too long for one QR symbol is refused with 422. Keep it short and the cell size small, because a code that is to be scanned must fit the paper. A person who double-clicks Check in should not get two cards, so give the job an Idempotency-Key made from the reservation, such as checkin-<reservation id>. A guest’s name is receipt content, not an identifier: keep it out of client_reference_id and metadata, which are for your own ids and take no personal data.
2. The guest bill
Trigger: the folio is closed at check-out, or the table is paid.
What goes on it: the hotel, a bill number, one row for each charge with quantity and amount, a rule, a bold total, how it was paid, and a QR code to the bill online.
| Room | 3 | 390.00 |
| Breakfast | 3 | 36.00 |
| City tax | 3 | 9.00 |
| Total EUR | 435.00 |
![]() |
| Room | 3 | 390.00 |
| Breakfast | 3 | 36.00 |
| City tax | 3 | 9.00 |
| Total EUR | 435.00 |
![]() |
[
{
"type": "text",
"text": "Hotel Harbour",
"align": "center",
"bold": true,
"size": 2
},
{
"type": "text",
"text": "Bill 2026-0457, room 214",
"align": "center"
},
{
"type": "table",
"columns": [
"*",
3,
{
"width": 9,
"align": "right"
}
],
"rows": [
[
"Room",
"3",
"390.00"
],
[
"Breakfast",
"3",
"36.00"
],
[
"City tax",
"3",
"9.00"
],
{
"type": "rule"
},
[
{
"text": "Total EUR",
"bold": true
},
"",
{
"text": "435.00",
"bold": true
}
]
]
},
{
"type": "text",
"text": "Paid by card. Thank you!",
"align": "center"
},
{
"type": "qr",
"data": "https://example.com/bills/2026-0457",
"cell": 4,
"align": "center"
}
]A bill headed Hotel Harbour for room 214 with bill number 2026-0457, three rows for room, breakfast and city tax with a quantity of 3 and amounts of 390.00, 36.00 and 9.00, a rule, a bold total of 435.00 EUR, a thank-you line and a QR code.
H o t e l H a r b o u r
Bill 2026-0457, room 214
Room 3 390.00
Breakfast 3 36.00
City tax 3 9.00
------------------------------------------------
Total EUR 435.00
Paid by card. Thank you!Pitfalls. Money is text. Format it yourself, and make the amount column wide enough for the longest value you will print. Write the currency as a code such as EUR: the euro sign is not in every printer’s character set (see the box below). A reprint is a new print, so it gets a new key, bill-<number>-2; the same key would return the first job and print nothing. Whether a printed bill meets the fiscal rules of your country is a question for your fiscal software and your accountant. Tillcast prints the document you send.
3. The kitchen ticket
Trigger: an order is sent to the kitchen or the bar.
What goes on it: the station, the table, a ticket number, the time, then each item in large bold type with its changes and allergies underneath, and the course.
| 2x | Margherita |
| no basil | |
| 1x | Salmon |
| ALLERGY: nuts |
| 2x | Margherita |
| no basil | |
| 1x | Salmon |
| ALLERGY: nuts |
[
{
"type": "text",
"text": "KITCHEN",
"align": "center",
"bold": true,
"size": 2
},
{
"type": "text",
"text": "Table 7 Ticket 4711-2",
"bold": true
},
{
"type": "text",
"text": "19:42"
},
{
"type": "rule"
},
{
"type": "table",
"columns": [
4,
"*"
],
"rows": [
[
{
"text": "2x",
"bold": true,
"size": 2
},
{
"text": "Margherita",
"bold": true,
"size": 2
}
],
[
"",
"no basil"
],
[
{
"text": "1x",
"bold": true,
"size": 2
},
{
"text": "Salmon",
"bold": true,
"size": 2
}
],
[
"",
"ALLERGY: nuts"
]
]
},
{
"type": "rule"
},
{
"type": "text",
"text": "Course 2: fire when table 7 asks",
"bold": true
}
]A kitchen ticket headed KITCHEN in large letters, table 7, ticket 4711-2, the time 19:42, then 2x Margherita and 1x Salmon in large bold type with the notes no basil and ALLERGY: nuts under them, and a line about the second course.
K I T C H E N
Table 7 Ticket 4711-2
19:42
------------------------------------------------
2 x M a r g h e r i t a
no basil
1 x S a l m o n
ALLERGY: nuts
------------------------------------------------
Course 2: fire when table 7 asksPitfalls. With some printers delivery is at least once (Star CloudPRNT, for example), so a kitchen can occasionally get the same ticket twice; with others a job can end failed although it printed (Epson Server Direct Print, for example). The ticket number in the document makes the second copy easy to spot and throw away; an Idempotency-Key such as kitchen-<order>-<ticket> protects the API call but not the paper. A double-size line holds half as many characters: in the 27 columns that are left on a 32-column 58 mm profile, an item name of 13 characters fits and one of 14 breaks after its thirteenth, because text wraps by characters, not at words. Keep item names short. If a kitchen printer is switched off, its jobs wait, up to 50, and the 51st is refused with 429 queue_full. A ticket that prints an hour late is worse than none, so set expires_in to a short time, for example 900 seconds (15 minutes). The default is 24 hours.
4. The order pick-up slip
Trigger: an order is paid at the counter or accepted online.
What goes on it: the pick-up number in very large type, a short list of the items, the time it will be ready, and a barcode that the counter scanner reads.
![]() |
![]() |
[
{
"type": "text",
"text": "Harbour Cafe",
"align": "center",
"bold": true
},
{
"type": "text",
"text": "Pick-up number",
"align": "center"
},
{
"type": "text",
"text": "A-42",
"align": "center",
"bold": true,
"size": 6
},
{
"type": "text",
"text": "2 coffees, 1 lemon cake",
"align": "center"
},
{
"type": "text",
"text": "Ready about 12:25",
"align": "center"
},
{
"type": "barcode",
"data": "A-42",
"symbology": "code128",
"hri": true,
"align": "center"
}
]A pick-up slip from Harbour Cafe with the pick-up number A-42 in very large type, the items, the ready time of about 12:25 and a CODE128 barcode.
Harbour Cafe
Pick-up number
A - 4 2
2 coffees, 1 lemon cake
Ready about 12:25Pitfalls. The size of a character goes up to 6, and a line of size 6 holds a sixth as many characters: 5 at 58 mm. A barcode is wider than it looks, and Tillcast does not check its width against the paper: the job is accepted, and what a printer does with a symbol that is too wide is not known. CODE128 takes 11 modules for each character and 35 for the start, the check digit and the stop, so at the default module width of 2 an 80 mm paper (576 dots) holds 23 characters and a 58 mm paper of 384 dots holds 14 (13 on a profile of 360 dots). A pick-up number of 3 to 5 characters is safe on both. If you need more data, use a QR code.
5. The housekeeping or maintenance note
Trigger: a guest asks for something, or a room’s status changes in the PMS.
What goes on it: the room, the request, when it was made, the priority and who reported it, a place to tick off the work, and a ticket number.
| Requested | 19:42 |
| Priority | Normal |
| Reported by | Front desk |
| Requested | 19:42 |
| Priority | Normal |
| Reported by | Front desk |
[
{
"type": "text",
"text": "HOUSEKEEPING",
"align": "center",
"bold": true,
"size": 2
},
{
"type": "text",
"text": "Room 214: extra towels",
"bold": true
},
{
"type": "table",
"columns": [
"*",
{
"width": 12,
"align": "right"
}
],
"rows": [
[
"Requested",
"19:42"
],
[
"Priority",
"Normal"
],
[
"Reported by",
"Front desk"
]
]
},
{
"type": "rule"
},
{
"type": "text",
"text": "[ ] Delivered"
},
{
"type": "text",
"text": "[ ] Guest informed"
},
{
"type": "text",
"text": "Ticket HK-0091",
"align": "right"
}
]A housekeeping note headed HOUSEKEEPING in large letters, Room 214: extra towels, a small table with the time requested, the priority and who reported it, a rule, two empty checkboxes written as square brackets, and the ticket number HK-0091.
H O U S E K E E P I N G
Room 214: extra towels
Requested 19:42
Priority Normal
Reported by Front desk
------------------------------------------------
[ ] Delivered
[ ] Guest informed
Ticket HK-0091Pitfalls. Write a checkbox as [ ], not as a ballot box character. On a printer whose code page lacks a character, it prints as ? (see the box below). A guest’s own words in a request field print as they are written: nothing in the text of a block can be markup or a printer command. A control character (a tab, for example) is refused with 422 document_invalid, so strip those from free text first. A note that is not urgent can have a long expires_in, so it still prints when a printer comes back online in the morning.
WarningPaper width and special characters
On the default profiles a line holds 48 characters on 80 mm paper; the 58 mm profiles hold 30 to 35, and the default 58 mm profile of Star printers holds 32. Text longer than a line wraps by characters, not at words: Scan to join. Network: Harbour-Guest fits on 80 mm paper, and on 58 mm it breaks in the middle of the network name. A character that the printer’s code page lacks prints as ? and is reported in the job’s warnings: with a profile that uses code page 852 (star-starprnt-cp852-80mm is one), the euro sign and a ballot box both come back as character_unmappable, while Polish and German letters do not. Write amounts with a currency code, use ASCII for symbols, and print a sample once before you rely on a character.
Duplicates and keys
An Idempotency-Key makes the API call safe to retry: the same key and the same body return the first job and print nothing more. It does not stop a printer from printing twice when its confirmation is lost, which is why the kitchen ticket carries a number. One key for each print you intend:
| Ticket | Example key | A reprint |
|---|---|---|
| Check-in card | checkin-<reservation id> |
checkin-<reservation id>-2 |
| Guest bill | bill-<number> |
bill-<number>-2 |
| Kitchen ticket | kitchen-<order>-<ticket> |
a new ticket number |
| Pick-up slip | pickup-<order> |
pickup-<order>-2 |
| Housekeeping note | hk-<ticket> |
hk-<ticket>-2 |
Keys are 1 to 64 visible ASCII characters and are remembered for 24 hours, or for as long as the job can still print if that is longer (a long expires_in makes it longer). Receipt content is deleted when a job is printed, failed, cancelled or expired, and it is never written to logs; the security page has the details.
Next steps
- Print your first receipt with one API call sends one of these documents.
- To see these receipts in your own page before they print, read Preview a receipt in the browser with @tillcast/preview.
- The docs page Receipt documents describes every block, and the quickstart goes from sign-up to a first receipt.
- Pricing explains how production is billed.

