• tutorial
  • curl
  • typescript
  • python
  • job-status
  • testing

Print your first receipt with one API call

Send a receipt to a cloud printer with one API call, in curl, TypeScript or Python: a test print, a first document, job statuses, safe retries and errors.

You print a receipt with Tillcast by sending one HTTPS request: POST /v1/printers/{printer}/jobs with a document, an array of blocks. Tillcast renders the document for that printer, queues the job, and the printer picks it up the next time it asks for work. Every call below is shown in curl, in TypeScript with @tillcast/sdk and in Python with tillcast: pick a language in any code box and the others follow.

What you need

  • A Tillcast account. Sign up in the dashboard with an e-mail address and a password.
  • A connected printer. Add it in the dashboard, then type its URL, shown once, into the printer’s own settings. Tillcast supports printers that ask a server for work: printers that support Star CloudPRNT, and Epson printers with Server Direct Print (Star setup, Epson setup). Other makers are not supported yet; the Printers page shows each maker’s status. Star, CloudPRNT, Epson and Server Direct Print are names of their makers, used here to say which printers work with Tillcast.
  • An API key. In the dashboard, open API keys and create one with the scopes jobs:write, jobs:read and printers:read. The key is shown once.
  • The printer’s id, prn_..., from the printer’s page in the dashboard.
  • A way to call the API. curl needs nothing, but the shell loops below use jq. TypeScript needs Node.js 18 or later, Python needs 3.10 or later.
Choose a language
# nothing to install
npm install @tillcast/sdk
pip install tillcast
export TILLCAST_API_KEY="tc_rk_live_..."
export TILLCAST_PRINTER_ID="prn_..."

WarningKeys print on real paper

Every Tillcast key is live, so a job you send comes out of a real printer. Keep the key in an environment variable on your server, never in a web page, and pin the SDK version (pre-1.0). A printer is billable in a month when it was connected for at least an hour in total or printed at least one job; welcome and test prints are free (see pricing).

Step 1: send a test print

Check that the address, the printer and the paper work before you print your own document. The test print queues one test page (a heading, the printer’s name, the time in UTC, a small table, one line in each type style, a cut). It is a job of kind test, never billed, and a printer takes at most 5 a minute and 3 waiting at a time (the next is 429 rate_limited).

Choose a language
curl -s -X POST https://api.tillcast.com/v1/printers/$TILLCAST_PRINTER_ID/test-print \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Idempotency-Key: first-test-1"
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": "first-test-1",
});
console.log(test.id, test.kind, test.status);
import os

from tillcast import Tillcast

client = Tillcast(token=os.environ["TILLCAST_API_KEY"])

test = client.printers.test_print(
    printer=os.environ["TILLCAST_PRINTER_ID"],
    idempotency_key="first-test-1",
)
print(test.id, test.kind, test.status)

The TypeScript code has no type annotations: it runs as plain JavaScript (save it as test-print.mjs), and as TypeScript it compiles in an ES module project with strict off. The answer is the job, with kind test and status queued; the printer prints it at its next poll. The dashboard’s Test print button makes the same call. Use a new Idempotency-Key for each test page (first-test-2, …): the same key returns the first job and prints nothing.

Step 2: print a receipt of your own

A document is an array of blocks in print order: a large centred title, a line of text, and a table with two columns (the first takes the space that is left, the second is 9 characters wide and aligned right). The rule block draws a line across the paper.

Choose a language
curl -s -X POST https://api.tillcast.com/v1/printers/$TILLCAST_PRINTER_ID/jobs \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Idempotency-Key: order-4711-bill" \
  -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"], ["Lemon cake", "4.20"], {"type": "rule"},
                [{"text": "Total", "bold": true}, {"text": "7.60", "bold": true}]]}
    ],
    "client_reference_id": "order-4711"
  }'
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);
import os

from tillcast import Tillcast

client = Tillcast(token=os.environ["TILLCAST_API_KEY"])

job = client.jobs.create(
    printer=os.environ["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",
)
print(job.id, job.status, job.warnings)

This is what the printer prints, drawn with the same renderer as @tillcast/preview. The picture is an approximation: the paper itself is the only exact output. The tabs show the same receipt as JSON (the document you send) and as plain text.

Views of the receipt
Paper width
Harbour Cafe
Table 7
Harbour Cafe
Table 7
[
  {
    "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
        }
      ]
    ]
  }
]

A receipt headed Harbour Cafe in large letters, then Table 7. Two lines, Flat white 3.40 and Lemon cake 4.20, a rule, and a bold total of 7.60.

            H a r b o u r   C a f e 
                     Table 7
Flat white                                  3.40
Lemon cake                                  4.20
------------------------------------------------
Total                                       7.60
The receipt of order 4711 as the printer prints it, on 80 mm and 58 mm paper.

Four things to know:

  • The text of a block prints as it is written. A |, a { or an underscore needs no escaping: nothing inside a block is markup.
  • Tillcast checks the document when it accepts the job. A mistake is an answer to your request, not a job that fails on the paper later.
  • client_reference_id is your own id, such as an order number. It is not unique, it takes no personal data, and GET /v1/jobs?client_reference_id= finds jobs by it.
  • A job carries a document of blocks or receiptline text, never both. ReceiptLine is a markup language for receipt printers. Both are supported today; other formats may follow, none is decided. Blocks are the way to start.

The answer is 201 with the job. Abridged, from a run against a local server:

{
  "id": "job_01M5DK19H0HXFXAZ24JB9WBX9P",
  "object": "job",
  "kind": "api",
  "status": "queued",
  "size_bytes": 589,
  "profile": "star-starprnt-utf8-80mm",
  "transport": "cloudprnt-star.1",
  "warnings": [],
  "client_reference_id": "order-4711",
  "created_at": "2026-10-20T21:21:17Z",
  "expires_at": "2026-10-21T21:21:17Z"
}

size_bytes is the size of what the printer is sent, profile the printer profile the document was rendered for, and warnings lists anything the renderer did that you did not ask for, such as a character the printer cannot print.

Step 3: follow the job

A job moves through a small set of states. Read it with GET /v1/jobs/{job}, or client.jobs.get in the SDKs.

The states of a job. A job ends in printed, failed, cancelled or expired.A job starts as queued. When the printer takes it the job is delivered, and when the printer reports the result it becomes printed or failed. A queued job can also be cancelled by you, or expire if no printer takes it before expires_at.queuedwaiting12deliveredtaken3printedfinal4you cancel itcancelledfinal5expires_at passedexpiredfinal6failedfinal
  1. queued: the API accepted the document, rendered it for the printer's profile and put the job in the printer's queue. A printer holds at most 50 waiting jobs.
  2. delivered: the printer asked for work, was given the job and took it.
  3. printed: the printer reported success.
  4. cancelled: you cancelled a queued job with POST /v1/jobs/{job}/cancel. A job the printer has already taken cannot be cancelled.
  5. expired: no printer took the job before expires_at. The default is 24 hours; expires_in sets it from 60 seconds to 7 days. A job that was taken and never confirmed can also end expired; when delivered_at is set it may have printed.
  6. failed: the printer reported an error, or it was given the job and sent no result when it should have (an Epson that reports nothing within 120 seconds ends failed with the reason result_missing). The job's reason and result_code say why.
The states of a job. A job ends in printed, failed, cancelled or expired. A job starts as queued. When the printer takes it the job is delivered, and when the printer reports the result it becomes printed or failed. A queued job can also be cancelled by you, or expire if no printer takes it before expires_at.

Webhooks, which would tell you without polling, are planned and do not exist yet, so read the job. A printer asks for work every few seconds (5 seconds by default on the Star printer we tested), so asking faster is pointless. The code continues step 2 (client and job).

Choose a language
export JOB_ID="job_..."   # the id from step 2
while true; do
  STATUS=$(curl -s https://api.tillcast.com/v1/jobs/$JOB_ID \
    -H "Authorization: Bearer $TILLCAST_API_KEY" | jq -r .status)
  echo "$STATUS"
  case "$STATUS" in printed|failed|expired|cancelled) break ;; esac
  sleep 5
done
async function waitForResult(jobId) {
  for (let attempt = 0; attempt < 12; attempt++) {
    const job = await client.jobs.get({ job: jobId });
    if (["printed", "failed", "expired", "cancelled"].includes(job.status)) return job;
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
  throw new Error(`job ${jobId} is not final after a minute`);
}

const result = await waitForResult(job.id);
console.log(result.status, result.reason, result.result_code);
import time


def wait_for_result(job_id):
    for _ in range(12):
        job = client.jobs.get(job=job_id)
        if job.status in ("printed", "failed", "expired", "cancelled"):
            return job
        time.sleep(5)
    raise TimeoutError(f"job {job_id} is not final after a minute")


result = wait_for_result(job.id)
print(result.status, result.reason, result.result_code)

With the printer’s spooler on, which Epson lists for some printers and firmware, an Epson reports a job as printed when it has accepted the page, so a cover opened or paper out after that is not reported. What the model we printed on reports for a cover opened or paper out has not been tried yet. The docs page Jobs explains the job states and why delivery to a Star printer is at least once.

Step 4: make a retry safe

Networks fail after a request has been accepted. Send an Idempotency-Key with every job (1 to 64 visible ASCII characters, one key for each print you intend). The same request with the same key returns the first job with status 200 and the header Idempotent-Replayed: true, and nothing is printed twice.

Choose a language
for i in 1 2; do
  curl -s -D - -o /dev/null -X POST https://api.tillcast.com/v1/printers/$TILLCAST_PRINTER_ID/jobs \
    -H "Authorization: Bearer $TILLCAST_API_KEY" \
    -H "Idempotency-Key: order-4711-kitchen" \
    -H "Content-Type: application/json" \
    -d '{"document": [{"type": "text", "text": "Table 7: flat white"}], "client_reference_id": "order-4711"}' \
    | grep -i -E "^HTTP|^idempotent-replayed"
done
const send = () =>
  client.jobs
    .create({
      printer: process.env.TILLCAST_PRINTER_ID,
      "Idempotency-Key": "order-4711-kitchen",
      document: [{ type: "text", text: "Table 7: flat white" }],
      client_reference_id: "order-4711",
    })
    .withRawResponse();

const first = await send();
const again = await send();

console.log(first.rawResponse.status, first.data.id);
console.log(again.rawResponse.status, again.rawResponse.headers.get("idempotent-replayed"), again.data.id);
request = dict(
    printer=os.environ["TILLCAST_PRINTER_ID"],
    idempotency_key="order-4711-kitchen",
    document=[{"type": "text", "text": "Table 7: flat white"}],
    client_reference_id="order-4711",
)

first = client.jobs.with_raw_response.create(**request)
again = client.jobs.with_raw_response.create(**request)

print(first.status_code, first.data.id)
print(again.status_code, again.headers.get("idempotent-replayed"), again.data.id)

The first answer is 201, the second 200 with the same job id. The same key with another body is 422 idempotency_key_reused. Keys are remembered for 24 hours, or as long as a job can still print if that is longer.

NoteWhat the key does not cover

A key protects the API call, not the paper. On a Star printer, delivery is at least once: if the printer’s confirmation is lost, the receipt can print twice. An Epson is not offered a job a second time, but a job can end failed although it printed. The SDKs retry 408, 429 and 5xx twice on their own (Python also 409), waiting for Retry-After up to 60 seconds, but not a timeout or a dropped connection: there the job may already exist. In a request handler pass maxRetries: 0 (max_retries 0 in Python), record the order in your own system first, and retry yourself with the same key.

Step 5: read the errors

Every error has the same shape: a type, a code to branch on, a message, a param that names the field, and a request_id to quote when you ask for help. A document with a bad block is 422 document_invalid, and param is the path of the first problem. This document has a table of two columns and a row of three cells:

Choose a language
curl -s -X POST https://api.tillcast.com/v1/printers/$TILLCAST_PRINTER_ID/jobs \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Idempotency-Key: order-4713-bill" \
  -H "Content-Type: application/json" \
  -d '{"document": [
        {"type": "text", "text": "Harbour Cafe"},
        {"type": "table", "columns": ["*", 9], "rows": [["Flat white", "3.40", "1"]]}
      ]}'
import { Tillcast } from "@tillcast/sdk";

try {
  await client.jobs.create({
    printer: process.env.TILLCAST_PRINTER_ID,
    "Idempotency-Key": "order-4713-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);
}
from tillcast.errors import UnprocessableEntityError

try:
    client.jobs.create(
        printer=os.environ["TILLCAST_PRINTER_ID"],
        idempotency_key="order-4713-bill",
        document=[
            {"type": "text", "text": "Harbour Cafe"},
            {"type": "table", "columns": ["*", 9], "rows": [["Flat white", "3.40", "1"]]},
        ],
    )
except UnprocessableEntityError as err:
    error = err.body.error
    print(error.code, error.param, error.message, error.request_id)

Here code is document_invalid and param is document[1].rows[0]: block 1 is the table, row 0 its first row. The message says the row “must have at most 2 cells (as many as the table has columns)”. No job is made, and the key stays free. The codes you will meet first:

Status Code What to do
401 invalid_api_key The key is wrong or revoked.
403 insufficient_scope The key lacks the scope, for example jobs:write.
404 resource_missing No such printer, or it belongs to another organization.
409 customer_suspended, location_suspended The customer or location is paused.
422 document_invalid Mend the block that param names and send again.
422 idempotency_key_reused The key was used for another request.
429 queue_full The printer has 50 jobs waiting. Wait for Retry-After.

If your software serves many venues

A software vendor that sets printers up for its own customers can make a customer, a location and a printer with the same API. Use a separate key with the scopes customers:read, customers:write, printers:read and printers:write (the reads are for searches and for a printer’s status), and a second client. The printer’s URL is shown once, in the answer that makes the printer (a new one comes only when you rotate the secret or move the printer to another customer). It is a password: hand it to the person who sets up the printer, and do not log it.

Choose a language
export TILLCAST_SETUP_KEY="tc_rk_live_..."
CUSTOMER=$(curl -s https://api.tillcast.com/v1/customers \
  -H "Authorization: Bearer $TILLCAST_SETUP_KEY" \
  -H "Idempotency-Key: acct-1042-customer" -H "Content-Type: application/json" \
  -d '{"name": "Sample Hotel Group", "client_reference_id": "acct-1042"}' | jq -r .id)
LOCATION=$(curl -s https://api.tillcast.com/v1/customers/$CUSTOMER/locations \
  -H "Authorization: Bearer $TILLCAST_SETUP_KEY" \
  -H "Idempotency-Key: acct-1042-old-town" -H "Content-Type: application/json" \
  -d '{"name": "Old Town", "client_reference_id": "prop-17"}' | jq -r .id)
curl -s https://api.tillcast.com/v1/locations/$LOCATION/printers \
  -H "Authorization: Bearer $TILLCAST_SETUP_KEY" \
  -H "Idempotency-Key: prop-17-reception" -H "Content-Type: application/json" \
  -d '{"name": "Reception left", "client_reference_id": "prop-17-reception"}'
# the answer holds the printer's url, shown once: it holds the printer's secret
const setup = new TillcastClient({ token: process.env.TILLCAST_SETUP_KEY });

const customer = await setup.customers.create({
  "Idempotency-Key": "acct-1042-customer",
  name: "Sample Hotel Group",
  client_reference_id: "acct-1042",
});
const location = await setup.locations.create({
  customer: customer.id,
  "Idempotency-Key": "acct-1042-old-town",
  name: "Old Town",
  client_reference_id: "prop-17",
});
const printer = await setup.printers.create({
  location: location.id,
  "Idempotency-Key": "prop-17-reception",
  name: "Reception left",
  client_reference_id: "prop-17-reception",
});
console.log(printer.id); // printer.url is shown once: it holds the printer's secret
setup = Tillcast(token=os.environ["TILLCAST_SETUP_KEY"])

customer = setup.customers.create(
    idempotency_key="acct-1042-customer",
    name="Sample Hotel Group",
    client_reference_id="acct-1042",
)
location = setup.locations.create(
    customer=customer.id,
    idempotency_key="acct-1042-old-town",
    name="Old Town",
    client_reference_id="prop-17",
)
printer = setup.printers.create(
    location=location.id,
    idempotency_key="prop-17-reception",
    name="Reception left",
    client_reference_id="prop-17-reception",
)
print(printer.id)  # printer.url is shown once: it holds the printer's secret

Send a different Idempotency-Key for each create, and search by client_reference_id before you create, because that field is not unique. The docs page Provision a venue walks through the whole flow.

What does not exist yet

There is no preview call over HTTP. To see a receipt without spending paper, draw it in the browser with @tillcast/preview, which needs no key and makes no request. In your own tests use a fake client rather than the live API.

Next steps