Skip to navigation

Create a print job

Send a receipt to a printer: the request, the answer, what happens next and how to retry safely.

View as Markdown

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.

The API prints on real paper

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, and jobs:read to 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 in GET /v1/printers, which you can filter by client_reference_id. The printer does not have to be online: the job waits for it.
  • For the SDKs, npm install @tillcast/sdk or pip 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.

import { TillcastClient } from "@tillcast/sdk";
const client = new TillcastClient({ token: process.env.TILLCAST_API_KEY! });
const job = await client.jobs.create({
printer: process.env.TILLCAST_PRINTER_ID!,
"Idempotency-Key": `hello-${Date.now()}`,
document: [{ type: "text", text: "Hello from Tillcast" }],
});
console.log(job.id, job.status);

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

PartMeaning
printer, in the pathThe id of the printer, prn_.... A MAC address is not accepted.
Authorization headerBearer and your key. The SDKs set it from token.
Tillcast-Version headerOptional. The API version your code was written for, 2026-10-01 today. The SDKs do not send it, so they get the current version. See Versioning.
Idempotency-Key headerOptional, 1 to 64 visible ASCII characters. Makes a retry safe. In TypeScript it is the property "Idempotency-Key" of the request, and in Python the argument idempotency_key.
documentThe receipt, as an array of 1 to 1,000 blocks in print order. Send this or receiptline, exactly one of the two.
receiptlineThe receipt as text in ReceiptLine, for documents written for other ReceiptLine tools. See Advanced: ReceiptLine text.
client_reference_idOptional. Your own id for the job, 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. The default is 86,400 (24 hours). A kitchen ticket that is an hour late is worse than none, so give it a short time.

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.

{
"id": "job_01M466JX008T2V5X7Z9C1E3G5H",
"object": "job",
"printer": "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
"customer": "cus_c3x9k2m3",
"location": "loc_01M42YMFP03Q1P9N7M5K3H1G0F",
"kind": "api",
"status": "queued",
"size_bytes": 156,
"profile": "star-starprnt-utf8-80mm",
"transport": "cloudprnt-star.1",
"warnings": [],
"result_code": null,
"reason": null,
"client_reference_id": null,
"metadata": null,
"created_at": "2026-10-17T09:30:00Z",
"delivered_at": null,
"completed_at": null,
"expires_at": "2026-10-18T09:30:00Z"
}
  • id is what you read the job back with.
  • warnings lists what the renderer noticed in the document. It is always there, and empty when there is nothing to say.
  • profile is the profile the document was rendered for, and size_bytes is 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.

const status = await client.jobs.get({ job: job.id });
console.log(status.status, status.reason, status.result_code);

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 queued with POST /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, 429 or a 5xx. The Python package also retries 409, which cannot succeed for a suspended customer. The retry sends the same request, so it carries the same key.
  • They wait for the Retry-After header of the answer, up to 60 seconds for one wait, and otherwise 1 second and then 2. A queue_full answer sends Retry-After: 30, so one jobs.create can block for about a minute before it raises. In a request handler, set maxRetries (TypeScript) or max_retries (Python) to 0, on the client or on one call, and decide yourself what to do with a 429.
  • 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: TillcastTimeoutError or a TillcastError with no status in TypeScript, and an httpx error 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.

import { Tillcast, TillcastClient } from "@tillcast/sdk";
const client = new TillcastClient({ token: process.env.TILLCAST_API_KEY! });
const request: Tillcast.CreateJob = {
printer: process.env.TILLCAST_PRINTER_ID!,
"Idempotency-Key": "order-4711-kitchen",
document: [{ type: "text", text: "Table 7: flat white" }],
client_reference_id: "order-4711",
};
const first = await client.jobs.create(request).withRawResponse();
const again = await client.jobs.create(request).withRawResponse();
console.log(first.rawResponse.status, first.data.id);
console.log(again.rawResponse.status, again.rawResponse.headers.get("idempotent-replayed"), again.data.id);

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.

try {
await client.jobs.create({
printer: process.env.TILLCAST_PRINTER_ID!,
"Idempotency-Key": "order-4712-bill",
document: [
{ type: "text", text: "Harbour Cafe" },
{ type: "table", columns: ["*", 9], rows: [["Flat white", "3.40", "1"]] },
],
});
} catch (err) {
if (!(err instanceof Tillcast.UnprocessableEntityError)) throw err;
const { code, param, message, request_id } = err.body.error;
console.error(code, param, message, request_id);
}

The answer is 422.

{
"error": {
"type": "invalid_request_error",
"code": "document_invalid",
"message": "document[1].rows[0] must have at most 2 cells (as many as the table has columns).",
"param": "document[1].rows[0]",
"request_id": "req_01M466JX008T2V5X7Z9C1E3G5H"
}
}

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.

StatusCodeWhy, and what to do
401invalid_api_keyThe key is wrong, revoked or expired. Check the key.
403insufficient_scopeThe key lacks jobs:write. Make a key with the scope.
404resource_missingNo such printer. The id is wrong, the printer was deleted, it belongs to another organization, or the key is limited to one customer and the printer is another customer’s. A MAC address is not a printer id.
409customer_suspended, location_suspendedThe customer is suspended or the location is paused, so no job is queued. Retrying does not help until it is reactivated. See Suspension and pause.
413document_too_large, rendered_too_large, request_too_largeThe document, what it renders to or the request is over a limit. Send less. See Limits and refusals.
422document_invalidA block cannot be printed as it is said, or the job has both document and receiptline, or neither. param is the path of the first problem. See Errors in a document.
422document_emptyThe document has no block, or prints nothing.
422idempotency_key_reusedThe key was used for a different request. Use a new key for a new receipt.
429queue_fullThe printer already has 50 jobs waiting. Wait for the seconds in the Retry-After header.
500, 503internal_errorA problem on Tillcast’s side, and nothing was queued. Send the same request again with the same key.

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.

import { TillcastClient } from "@tillcast/sdk";
const client = new TillcastClient({ token: process.env.TILLCAST_API_KEY! });
const job = await client.jobs.create({
printer: process.env.TILLCAST_PRINTER_ID!,
"Idempotency-Key": "order-4711-bill",
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"],
["Lemon cake", "4.20"],
{ type: "rule" },
[{ text: "Total", bold: true }, { text: "7.60", bold: true }],
],
},
],
client_reference_id: "order-4711",
});
console.log(job.id, job.status, job.warnings);

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.

H a r b o u r C a f e
Table 7
Flat white 3.40
Lemon cake 4.20
--------------------------------
Total 7.60

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.

import { TillcastClient } from "@tillcast/sdk";
const client = new TillcastClient({ token: process.env.TILLCAST_API_KEY! });
const job = await client.jobs.create({
printer: process.env.TILLCAST_PRINTER_ID!,
"Idempotency-Key": "order-4712",
receiptline: "Harbour Cafe\nTable 7\n{width:*,9}\nFlat white | 3.40\nLemon cake | 4.20\n-\nTotal | 7.60",
client_reference_id: "order-4712",
});
console.log(job.id, job.status, job.warnings);
Harbour Cafe
Table 7
Flat white 3.40
Lemon cake 4.20
--------------------------------
Total 7.60

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.

import { TillcastClient } from "@tillcast/sdk";
const client = new TillcastClient({ token: process.env.TILLCAST_API_KEY! });
const test = await client.printers.testPrint({
printer: process.env.TILLCAST_PRINTER_ID!,
"Idempotency-Key": `test-${Date.now()}`,
});
console.log(test.id, test.kind, test.status);

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