# 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.

- Published: 2026-10-21
- Updated: 2026-10-25
- Tags: tutorial, curl, typescript, python, job-status, testing
- Author: Tillcast
- Canonical URL: https://tillcast.com/blog/print-your-first-receipt/
- Blog: https://tillcast.com/blog/

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](https://dashboard.tillcast.com/sign-up) 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](https://docs.tillcast.com/printers/star-setup), [Epson setup](https://docs.tillcast.com/printers/epson-setup)). Other makers are not supported yet; the [Printers](https://tillcast.com/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.

### curl

```sh
# nothing to install
```

### TypeScript

```sh
npm install @tillcast/sdk
```

### Python

```sh
pip install tillcast
```

```sh
export TILLCAST_API_KEY="tc_rk_live_..."
export TILLCAST_PRINTER_ID="prn_..."
```

> **Warning: Keys 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](https://tillcast.com/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`).

### curl

```sh
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"
```

### TypeScript

```ts
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);
```

### Python

```python
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.

### curl

```sh
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"
  }'
```

### TypeScript

```ts
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);
```

### Python

```python
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.

**Receipt: The receipt of order 4711 as the printer prints it, on 80 mm and 58 mm paper.**

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.

```json
[
  {"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}]]}
]
```

As text, at 48 characters a line:

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

Drawn at 80 mm (48 characters a line), 58 mm (32 characters a line).

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:

```json
{
  "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.

**Diagram: 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.

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.

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`).

### curl

```sh
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
```

### TypeScript

```ts
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);
```

### Python

```python
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](https://docs.tillcast.com/concepts/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.

### curl

```sh
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
```

### TypeScript

```ts
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);
```

### Python

```python
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.

> **Note: What 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:

### curl

```sh
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"]]}
      ]}'
```

### TypeScript

```ts
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);
}
```

### Python

```python
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.

### curl

```sh
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
```

### TypeScript

```ts
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
```

### Python

```python
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](https://docs.tillcast.com/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`](https://docs.tillcast.com/preview-a-receipt), which needs no key and makes no request. In your own tests use a fake client rather than the live API.

## Next steps

- The [quickstart](https://docs.tillcast.com/quickstart) and the page [Create a print job](https://docs.tillcast.com/create-a-print-job) have every field and every refusal.
- [Receipt documents](https://docs.tillcast.com/concepts/documents) describes all nine block types.
- The [pricing](https://tillcast.com/pricing/) page explains how production is billed.

---

Tillcast is a print API for receipt printers: your software sends a job and a printer in the venue prints it. https://tillcast.com/
