Skip to navigation

Jobs

What a job is, its states, how long it waits and what delivery guarantee you get.
View as Markdown

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.

curl https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/jobs \
-H "Authorization: Bearer $TILLCAST_API_KEY" \
-H "Idempotency-Key: order-4715" \
-H "Content-Type: application/json" \
-d '{
"document": [
{"type": "text", "text": "Harbour Cafe", "align": "center", "bold": true, "size": 2},
{"type": "text", "text": "Table 7", "align": "center"},
{"type": "table", "columns": ["*", {"width": 9, "align": "right"}],
"rows": [["Flat white", "3.40"], {"type": "rule"}, [{"text": "Total", "bold": true}, {"text": "3.40", "bold": true}]]}
],
"client_reference_id": "order-4715",
"metadata": {"table": "7"},
"expires_in": 3600
}'
FieldMeaning
documentThe receipt, as an array of 1 to 1,000 blocks in print order. See Receipt documents. Send this or receiptline, exactly one of the two.
receiptlineThe receipt as text in ReceiptLine, 1 byte to 256 KB. For documents written for other ReceiptLine tools. See Advanced: ReceiptLine text.
client_reference_idOptional. The id of this job in your own system, such as the order number, 1 to 128 characters. Not unique. No personal data. See Your own IDs.
metadataOptional. Up to 10 pairs, 1 KB in all. No personal data.
expires_inOptional. How many seconds the printer may be offered the job, from 60 to 604,800 (7 days). The default is 86,400 (24 hours).

The answer is 201 with the job. The same call with the same Idempotency-Key answers 200 with the job of the first call.

{
"id": "job_01M466JX008T2V5X7Z9C1E3G5H",
"object": "job",
"printer": "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
"customer": "cus_c3x9k2m3",
"location": "loc_01M42YMFP03Q1P9N7M5K3H1G0F",
"kind": "api",
"status": "queued",
"size_bytes": 455,
"profile": "star-starprnt-utf8-80mm",
"transport": "cloudprnt-star.1",
"warnings": [],
"result_code": null,
"reason": null,
"client_reference_id": "order-4715",
"metadata": {"table": "7"},
"created_at": "2026-10-16T10:00:00Z",
"delivered_at": null,
"completed_at": null,
"expires_at": "2026-10-16T11:00:00Z"
}
  • size_bytes is the size of what the printer is sent, the rendered document, and not the size of the document you sent.
  • profile is the profile the document was rendered for and transport the 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.
  • warnings is always there. It lists what the renderer noticed. See Warnings.
  • kind is api for your jobs, welcome for the first-connection receipt and test for a test print.

Job states

A job moves through these states. The last four are final.

StateMeaningFinal
queuedAccepted. Waiting for the printer’s next poll.No
deliveredThe printer has downloaded the job. Tillcast waits for its confirmation, past expires_at too, but not for ever. See Job lifetime.No
printedThe printer confirmed that it printed the job.Yes
failedThe printer reported an error or refused the job, or Tillcast no longer had the job’s bytes to give it. reason says why and result_code holds the printer’s own status code. With delivered_at set, the reasons result_missing and payload_unavailable do not say whether the page printed. See Job lifetime.Yes
expiredThe job’s lifetime ended before it was printed. With delivered_at null the printer never took it and nothing printed. With delivered_at set the printer took it and no confirmation came before the end: it may have printed, so look at the paper before you print again. See Job lifetime.Yes
cancelledThe job was cancelled while queued, or its printer was deleted, or its printer was moved with the waiting jobs cancelled.Yes

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.

What printed means on an Epson

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 failed with the reason result_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_at as expired, a delivered one 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 ends failed with the reason payload_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 then 404.

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 receiptline text 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_full and a Retry-After header.

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 with GET /v1/jobs, newest first. A key limited to one customer must pass printer. Both need the jobs:read scope.
  • The list has one filter on state: status=pending, which needs printer and lists the jobs waiting for that printer, oldest first. Any other status, such as queued or failed, is 400 parameter_invalid, and so is status together with client_reference_id. To find the failed jobs of a printer, list its jobs and read their status.
  • 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.