Skip to navigation

Integrate a point of sale

What a till or an order system needs to print receipts and tickets through Tillcast.
View as Markdown
The API prints on real paper

A key prints on real printers. Use a key made for the integration, keep it in an environment variable and never write it into code or logs.

This page is for the code that sits in your point of sale or order system. Set the printers up first with the quickstart, or, if your software sets printers up for its own customers, with Provision a venue from your software. The examples use the SDKs (npm install @tillcast/sdk, pip install tillcast); every call is also a plain HTTP request, shown as cURL.

What you need

  • An API key with the scope jobs:write, jobs:read if you read job states and printers:read if you look printers up. Make it in the dashboard, under API keys.
  • The id of each printer (prn_...) that the integration prints to. A till, a kitchen and a bar are three printers with three ids. Put your own name for each in its client_reference_id and look the printers up with GET /v1/printers?client_reference_id=kitchen-1.

Send a job

One job is one document for one printer, and Create a print job goes through the call field by field. The document is an array of blocks: text, tables, rules, QR codes, barcodes and images. Text that is not yours, such as a guest name or an item name, goes into a block as it is. Nothing in a block is markup, so there is nothing to escape.

import { TillcastClient } from "@tillcast/sdk";
const client = new TillcastClient({ token: process.env.TILLCAST_API_KEY! });
const job = await client.jobs.create({
printer: "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
"Idempotency-Key": "order-4714-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"],
{ type: "rule" },
[{ text: "Total", bold: true }, { text: "3.40", bold: true }],
],
},
],
client_reference_id: "order-4714",
expires_in: 600,
});
  • Idempotency-Key: one key per print you intend, for example the order number and the kind of paper (order-4714-bill, order-4714-kitchen). A retry with the same key answers the first job and prints nothing more. Keys are remembered for 24 hours.
  • client_reference_id: your order number. It is not unique and Tillcast never refuses it. Use it to find the jobs of an order later.
  • expires_in: how many seconds a printer may be offered the job. A kitchen ticket that is an hour late is worse than none, so choose a short time.

The answer is 201 with the job, and its warnings list what the renderer could not print as written. A printer that is off or offline takes the job when it is back, if the job has not expired.

Delivery and duplicates

A Star printer confirms a job after it printed, and a lost confirmation can make it ask for the job again. An Epson is not offered a job again, but a job that ends failed with result_missing may have printed. Make a second print harmless: do not make the paper the proof that something happened. If a job must not print twice, check its state with GET /v1/jobs/{job} before you send it again.

Find a job again

const found = await client.jobs.list({
client_reference_id: "order-4714",
printer: "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
});

A job is queued, delivered, printed, failed, expired or cancelled. See Jobs for what each means and for the reasons a job fails. With its spooler on, an Epson reports printed when it has accepted the page, so a cover opened after that is not reported.

When something goes wrong

  • 429: rate_limited, or queue_full when the printer already has 50 jobs waiting. Wait for the time in the Retry-After header (30 seconds for queue_full) and send the same request again with the same Idempotency-Key. Do not loop on queue_full: the queue empties as the printer prints, as you cancel jobs and as jobs pass their expires_at (24 hours by default), so a printer that is off keeps refusing until jobs in its queue expire. After a few tries, tell a person.
  • 409: the printer, its location or its customer is suspended or paused. Read the error code. See Errors and Suspension and pause.
  • 400, 413 or 422: your request is wrong, for example a block that cannot be printed as it is said (document_invalid, and param is the path of the block), a document that is too large or one that carries a printer command. What the printer’s profile cannot print as written is not refused: it prints, and warnings says what changed.
  • No answer, a 5xx, a timeout: send the same request again with the same Idempotency-Key and the same body. You get the first job, never a second one. The SDKs do this for a 5xx and not for a timeout or a dropped connection, so keep your own record of the print before you call and retry from it. See Retry safely and the table in Errors.

Check the printer first

Press Full test page on the printer’s page in the dashboard before you go live. It queues a long page with every barcode type, QR code and image the printer can be asked for, about 80 cm of paper. Print it on the printer you will use. The other button, Test print, queues a short page that only checks the address, the printer and the paper.

An agent that writes this integration should read Build with an agent first.