Create a print job
Send a receipt to a printer: the request, the answer, what happens next and how to retry safely.
A print job is one document for one printer. You create it with one call, POST /v1/printers/{printer}/jobs. Tillcast renders the document for the printer and queues it, and the printer takes it on its next poll and prints it. This is the call your software makes for every receipt, ticket and report.
A key prints on real printers. Keep it in an environment variable, never in code, and send your tries to the printer you mean to print on.
What you need
- An API key with the scope
jobs:write, andjobs:readto read a job back. Make it in the dashboard, under API keys. See Authentication and API keys. - The id of a printer,
prn_.... It is in the answer that adds the printer, in the printers list of the dashboard, and inGET /v1/printers, which you can filter byclient_reference_id. The printer does not have to be online: the job waits for it. - For the SDKs,
npm install @tillcast/sdkorpip install tillcast, version 0.2.0 or later. See SDKs.
The samples on this page read the key and the printer id from TILLCAST_API_KEY and TILLCAST_PRINTER_ID. If you have no key or printer yet, the quickstart sets both up step by step.
The smallest job
This job prints one line. The key in Idempotency-Key is new on every run, so every run prints. See Retry safely.
TypeScript
Python
cURL
To run a TypeScript sample, use Node 22.18 or later (Node 24 does too), which runs TypeScript directly: the types are stripped and nothing else is needed. Save the sample as send.mts and run node send.mts. Code that needs more than stripping the types, such as an enum or a constructor parameter property, is refused with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX: use a compiler or a loader, or run node --experimental-transform-types send.mts, which prints an experimental warning. The three tabs send the same request.
The request
The body is closed: a field that is not in this table is refused with 400 parameter_unknown. There is no template or data field: a template language and stored templates are in development and not available. Build the document in your code.
The answer
The answer is 201 with the job. It is queued.
idis what you read the job back with.warningslists what the renderer noticed in the document. It is always there, and empty when there is nothing to say.profileis the profile the document was rendered for, andsize_bytesis the size of what the printer is sent.
Tillcast renders the document when it accepts the job, so a document that cannot be printed is an answer to this request, as in When a job is refused, and not a job that fails later. All the fields are in Jobs.
What happens next
The printer polls Tillcast, every 5 seconds by default. At its next poll it downloads the job, prints it and confirms. The job moves from queued to delivered to printed, or ends failed, expired or cancelled. See Job states.
Read the job with its id. These lines continue the sample above.
TypeScript
Python
cURL
Here $JOB is the id from the answer. If the status is failed, reason and result_code say why. With its spooler on, an Epson answers printed when it has accepted the page, so the paper decides.
- Do not poll faster than you need. A printer takes a job within about one poll interval. Webhooks, which would tell you without polling, are planned and not built yet. See Webhooks and events.
- Find the jobs of an order with
GET /v1/jobs?client_reference_id=order-4711. See Jobs. - Cancel a job that is still
queuedwithPOST /v1/jobs/{job}/cancel. A job that the printer has downloaded cannot be cancelled. - Jobs are kept for 7 days after they end.
Retry safely
A call can fail after Tillcast has accepted it: a timeout, a dropped connection, a 5xx. If you send it again without a key, a second job is queued and a second receipt prints. With an Idempotency-Key, the retry answers the first job.
What the SDKs retry, and what they do not (checked in version 0.2.1 of both packages):
- They retry only when Tillcast answered: twice by default, when the status is
408,429or a5xx. The Python package also retries409, which cannot succeed for a suspended customer. The retry sends the same request, so it carries the same key. - They wait for the
Retry-Afterheader of the answer, up to 60 seconds for one wait, and otherwise 1 second and then 2. Aqueue_fullanswer sendsRetry-After: 30, so onejobs.createcan block for about a minute before it raises. In a request handler, setmaxRetries(TypeScript) ormax_retries(Python) to 0, on the client or on one call, and decide yourself what to do with a429. - They do not retry a timeout or a dropped connection, which are the cases where Tillcast may already have accepted the job. The call raises after one try:
TillcastTimeoutErroror aTillcastErrorwith no status in TypeScript, and anhttpxerror in Python. (The Python package retries when the connection is refused or cannot be made, because then nothing was sent, and not when the connection times out.) The default timeout is 60 seconds in both.
So the SDK does not cover a lost answer, and you must. Write down the print you intend before you call, and when the call raises without an answer, send the same request again yourself, with the same Idempotency-Key and the same body. Within 24 hours you get the first job back, never a second one. A request with another body is 422 idempotency_key_reused.
Use one key for each print you intend, for example the order number and the kind of paper (order-4711-bill, order-4711-kitchen), and a new key for a new receipt. This sample sends the same request twice, as a retry would.
TypeScript
Python
cURL
Run the cURL command twice to see the same. The first call answers 201. The second answers 200 with the header Idempotent-Replayed: true, and the job in the answer has the same id as the first. Nothing new is queued and nothing prints twice. The same key with a different body is 422 idempotency_key_reused. A key is remembered for 24 hours. See Idempotency.
Idempotency stops the duplicates that your retries make. A Star printer can still print a job twice after a power cut, so make a repeated print harmless. See Delivery and duplicates.
When a job is refused
A refusal is an HTTP status and an error with a stable code to branch on, a message for a person, the param the error is about and a request_id to quote when you ask for help. A refused create writes nothing and leaves its key free.
The most common refusal is a document that cannot be printed as it is said: 422 document_invalid, and param is the path of the first problem. This sample sends a table with two columns and a row of three cells. These lines continue the sample above.
TypeScript
Python
cURL
The answer is 422.
param counts from 0 in the order of the document: block 1 is the table, and row 0 is its first row. The message never holds a piece of your text. In the SDKs the error is an exception, Tillcast.UnprocessableEntityError in TypeScript and UnprocessableEntityError in Python, and the body above is its body.
These are the refusals you meet most often. Errors lists every code.
A receipt to copy
A title, a line with the table number and a table with two items, a rule and a total. This is the first document of Receipt documents, with the key and the order number of a real order.
TypeScript
Python
cURL
On paper this is what a 58 mm printer prints. The text view is 32 characters wide, and it cannot show bold, underline or inverse. It shows a line of double size with a space after every letter.
Every block, with its fields, is in Receipt documents. Text of your own, such as a name or an item, goes into a block as it is: nothing in a block is markup.
The same receipt as ReceiptLine text
If you already have documents written for other ReceiptLine tools, send the text in receiptline instead of document. In JSON a line break is \n. The blocks are the way to write a receipt: in ReceiptLine text the characters of the language are yours to escape. See Advanced: ReceiptLine text.
TypeScript
Python
cURL
See the paper: the test print
To see paper without writing a document, queue a test page. In the dashboard, press Test print on the printer’s page. With the API, call POST /v1/printers/{printer}/test-print, which takes no body and the scope jobs:write. The answer is a job whose kind is test, and the printer prints it at its next poll. Use a new Idempotency-Key each time: the same key answers the first test job and prints nothing.
TypeScript
Python
cURL
A test print is never billed. A printer takes at most 5 test prints in any minute and 3 waiting at a time, so a printer that is not online refuses the fourth with 429 rate_limited until it prints the three or an hour has passed. The short page and the full page, which shows every barcode type, QR code and image, are described in First connection.
Where to go next
- Write real receipts: Receipt documents, with every kind of block.
- Build the integration in your till or order system: Integrate a point of sale.
- Handle failure: Errors, Idempotency and Jobs.
- Install the packages: SDKs.
- Browse every operation in the API reference.