Jobs
What a job is
A job is one document for one printer. You create it under a printer with POST /v1/printers/{printer}/jobs and the jobs:write scope. The document is an array of blocks: text, tables, rules, codes and images. Tillcast renders it into the commands of the printer’s profile when it accepts the job, queues the result, and the printer downloads it on its next poll, prints it and confirms. Create a print job shows the call step by step, in cURL, TypeScript and Python.
The answer is 201 with the job. The same call with the same Idempotency-Key answers 200 with the job of the first call.
size_bytesis the size of what the printer is sent, the rendered document, and not the size of the document you sent.profileis the profile the document was rendered for andtransportthe step that was applied to the rendered bytes. A job keeps the profile it was rendered for, even if you change the printer’s profile later.warningsis always there. It lists what the renderer noticed. See Warnings.kindisapifor your jobs,welcomefor the first-connection receipt andtestfor a test print.
Job states
A job moves through these states. The last four are final.
delivered_at and completed_at hold the times. An expired job has no reason, and its completed_at is null until Tillcast writes its end. A queued job can be cancelled with POST /v1/jobs/{job}/cancel. A job that the printer has already downloaded cannot be cancelled, because it may be printing. The answer is 409 job_not_cancellable.
With the printer’s spooler on, which Epson lists for some printers and firmware, an Epson answers “printed” as soon as it has accepted the page. A cover opened or paper out after that is not reported, so the paper decides. Epson lists no spooler for the TM-m30III series, and what the model we printed on reports for a cover opened or paper out has not been tried. A page that was handed to an Epson and for which no result came back within 120 seconds ends failed with the reason result_missing. It does not say whether the page printed: look at the paper before you print again.
Delivery and duplicates
What happens to a job that the printer took depends on the printer.
- A Star printer gets each job at least once. If its confirmation never reaches Tillcast, for example after a power cut or a lost connection, Tillcast offers the job again and the printer may print it twice. Tillcast prefers a duplicate to a lost receipt.
- An Epson is not offered a job again once it has taken it. If no result comes back within 120 seconds, the job ends
failedwith the reasonresult_missing, although the page may have printed.
Design for this:
- Make a repeated print harmless, or detect it on your side.
- Create jobs with an
Idempotency-Key, so that retrying a failed API call does not queue a second job. See Idempotency.
Job lifetime
A job waits for its printer for 24 hours by default. You can set a shorter or a longer lifetime with expires_in, up to 7 days. Seven days lets an end-of-day report survive a weekend with the printer off. A kitchen order is useless after 30 minutes, so give it a short lifetime.
After expires_at the printer is no longer offered a job that it has not taken, and the API reports that job as expired at once. Tillcast writes the end of the job later, so completed_at is null until then. The end is written when the printer asks for that job by name, or when a new job finds the printer’s queue full. An ordinary poll does not write it. A job past its expires_at does not count against the 50 waiting jobs of the printer, so a printer that was off all night does not refuse the morning’s receipts because of jobs that expired.
A job that a printer has taken is not expired by the clock. Until expires_at a Star printer is offered it again at its next poll, until it confirms, which is why delivery to a Star printer is at least once. After expires_at a poll no longer offers it and the job stays delivered with completed_at null. A printer that asks for it by name is still served it while Tillcast holds its bytes, and a confirmation that arrives while the job is delivered ends it as printed.
That does not last for ever. A taken job that is never confirmed can end without the printer’s word in three ways:
- The queue needs the room. When a new job finds the queue full (50 entries, the expired ones included), Tillcast finishes every entry past its
expires_atasexpired, adeliveredone too. A confirmation after that no longer changes it. - The bytes are gone. Tillcast deletes the rendered bytes of a job when it ends. For a job that does not end, a time limit removes them from one hour after
expires_at. The clean-up runs in the background and can be late, so the hour is the earliest time and not a promise. When the printer then asks for the job by name there is nothing to give, and the job endsfailedwith the reasonpayload_unavailable. - The record is gone. A job that does not end is deleted from 7 days after
expires_at, and that clean-up can be late too. A read of the job is then404.
Read delivered_at on a job that ends this way. If it is null, the printer never took the job and nothing printed. If it is set, the printer took the job and may have printed it, whether it reads expired, or failed with the reason payload_unavailable, or, for an Epson, failed with result_missing. Look at the paper before you print again.
A Star job whose confirmation never comes therefore stays delivered until one of these happens, so choose your own time after which your software stops waiting and tells a person. An Epson is different: a page for which no result comes back within 120 seconds ends failed with the reason result_missing, as described above.
Jobs also stay queued while their customer is suspended or their location is paused. See Suspension and pause. A test print is offered for one hour only.
Job limits
- A document of blocks can hold up to 1,000 blocks, the
receiptlinetext can be up to 256 KB, and what a document renders to can be up to 256 KB of printer data. See Receipt documents. - A printer can have up to 50 waiting jobs. When its queue is full, a new job is refused with
429 queue_fulland aRetry-Afterheader.
A printer that is off or out of paper fills its queue after a while, so use long lifetimes only for jobs that need them. You can see what waits with GET /v1/jobs?printer=prn_...&status=pending, oldest first, and cancel what is no longer needed.
Knowing what happened
- When you create a job, the answer already says what the renderer made of the document: its size, its profile and its warnings. A mistake in the request is an answer to the request, and no job is made.
- Read a job with
GET /v1/jobs/{job}and list jobs withGET /v1/jobs, newest first. A key limited to one customer must passprinter. Both need thejobs:readscope. - The list has one filter on state:
status=pending, which needsprinterand lists the jobs waiting for that printer, oldest first. Any otherstatus, such asqueuedorfailed, is400 parameter_invalid, and so isstatustogether withclient_reference_id. To find the failed jobs of a printer, list its jobs and read theirstatus. - Do not poll for the state faster than you need. A printer takes a job within about one poll interval, 5 seconds by default. Webhooks, which tell you without polling, are planned and not built. See Webhooks and events.
- Jobs are kept for 7 days after they end. A job that does not end is kept until 7 days after its
expires_at. See Security and data.
The rendered bytes of a job are deleted as soon as the job is final. See Security and data.