> Tillcast is live: the API at https://api.tillcast.com/v1 and the dashboard at https://dashboard.tillcast.com. A key prints on real printers, so do not call the API unless asked. A job carries its receipt as "document", an array of blocks (the recommended way), or as "receiptline", ReceiptLine text, exactly one of the two: read https://docs.tillcast.com/create-a-print-job.md and https://docs.tillcast.com/concepts/documents.md before you write a job body. Do not code against what does not exist yet: webhooks, a template language, stored templates (a job has no template field), OAuth connections and connectors for Make, Zapier and n8n, and OAuth sign-in for the MCP server. SDKs for TypeScript (@tillcast/sdk, version 0.2.0 or later for blocks) and Python (tillcast) exist as pre-1.0 versions. To show a receipt in a web page without printing, there are the npm packages @tillcast/preview and @tillcast/html-render (0.x, no API key, no call to Tillcast to draw): read https://docs.tillcast.com/preview-a-receipt.md. The docs are the source of truth: check the index https://docs.tillcast.com/llms.txt and https://docs.tillcast.com/roadmap.md before you code against anything. For clean Markdown of any page, append .md to the page URL. The Tillcast MCP server is live at https://api.tillcast.com/mcp and takes an API key as a bearer token (setup: https://docs.tillcast.com/connect-an-ai-assistant.md). It acts on the live account and its tools print on real paper, so do not connect to it or call its tools unless the owner asked you to. The MCP server at https://docs.tillcast.com/_mcp/server is a different one: it only searches these docs and cannot call the Tillcast API.

# Jobs

> Tillcast job states, lifetime and limits, and what delivery means for a Star and for an Epson printer.

## 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](/concepts/documents): text, tables, rules, codes and images. Tillcast renders it into the commands of the printer's [profile](/printers/profiles) 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](/create-a-print-job) shows the call step by step, in cURL, TypeScript and Python.

```bash wordWrap
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
  }'
```

| Field                 | Meaning                                                                                                                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document`            | The receipt, as an array of 1 to 1,000 blocks in print order. See [Receipt documents](/concepts/documents). Send this or `receiptline`, exactly one of the two.                           |
| `receiptline`         | The receipt as text in ReceiptLine, 1 byte to 256 KB. For documents written for other ReceiptLine tools. See [Advanced: ReceiptLine text](/concepts/documents#advanced-receiptline-text). |
| `client_reference_id` | Optional. 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](/concepts/client-reference-id).          |
| `metadata`            | Optional. Up to 10 pairs, 1 KB in all. No personal data.                                                                                                                                  |
| `expires_in`          | Optional. 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.

```json wordWrap
{
  "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](/concepts/documents#warnings).
* `kind` is `api` for your jobs, `welcome` for the [first-connection receipt](/printers/first-connection) and `test` for a [test print](/printers/first-connection#test-print).

## Job states

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

| State       | Meaning                                                                                                                                                                                                                                                                                                                                  | Final |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| `queued`    | Accepted. Waiting for the printer's next poll.                                                                                                                                                                                                                                                                                           | No    |
| `delivered` | The printer has downloaded the job. Tillcast waits for its confirmation, past `expires_at` too, but not for ever. See [Job lifetime](#job-lifetime).                                                                                                                                                                                     | No    |
| `printed`   | The printer confirmed that it printed the job.                                                                                                                                                                                                                                                                                           | Yes   |
| `failed`    | The 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](#job-lifetime). | Yes   |
| `expired`   | The 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](#job-lifetime).                      | Yes   |
| `cancelled` | The 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](/api/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](/concepts/suspension). 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](/concepts/documents#limits-and-refusals).
* 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](/events/webhooks).
* 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](/security#how-long-data-is-kept).

The rendered bytes of a job are deleted as soon as the job is final. See [Security and data](/security).