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

# Print a test page

POST https://api.tillcast.com/v1/printers/{printer}/test-print

Queues one test page for a printer: a ReceiptLine document that is rendered
with the printer's own profile, so it has the width, the character set and
the commands of that printer (StarPRNT for a Star, ESC/POS for an Epson) and
its rules and its table reach the edges of the paper. `page` chooses which
page. `basic`, the default, shows a heading, the printer's name, the time in
UTC, a table of three columns with lines, and one line in each type style
(normal, bold, double width, double height, double width and height,
underlined, inverted), then a cut. `full` shows the same heading and then,
in five sections, the type styles, three alignments and the table with a
cell that wraps, the Tillcast mark with a ruler, a gray ramp and a density
bar as wide as the paper, fifteen barcodes (CODE128, CODE39, CODE93, ITF,
Codabar, EAN-13, EAN-8, UPC-A and UPC-E at the module widths that matter)
and ten QR codes (the four error correction levels, cell sizes 3 to 8, a
Polish sentence and a longer text): print it on a Star and on an Epson and
hold the two papers side by side. Any other value of `page` is
`400 parameter_invalid`, and so is a `page` that is given twice. The page is
rendered the way a job is: the job lists the `profile` and the `transport`
it was made with and its `warnings`, and a printer whose model needs a
profile that it does not have is refused with `422 profile_mismatch`. The
Epson form has not been confirmed on a device yet, so a page that does not
print on an Epson is not necessarily a mistake in how the printer was set
up. The printer prints it the next time it polls, and the page is offered
for one hour. It is a job of kind `test`: it is never billed and does not
count as a print of yours. A printer takes at most 5 test prints in a minute
and 3 waiting at a time, of either page (`429 rate_limited`, with
`Retry-After`), and its queue of 50 jobs applies as for any job. The two
limits stop a loop or a double click and are not a quota: calls made at the
same moment can pass them, up to that queue. Send an `Idempotency-Key` so
that a retry does not queue a second page; the same key with another `page`
is `422 idempotency_key_reused`. The dashboard calls it with the access
token of a signed-in owner or developer instead of a key, naming the
organization in `Tillcast-Organization`; the answer is the same, and the
call writes an audit entry. A person is refused with `permission_denied`
(a viewer), `organization_suspended`, `organization_required` (no header) or
`resource_missing` (not a member of that organization). `{printer}` is the
printer's id; a MAC address is not accepted there.

**Scope:** `jobs:write`.

Reference: https://docs.tillcast.com/api-reference/printers/test-print

## Authentication

- `Authorization` header (bearer token, required) — A restricted API key, `tc_rk_live_` and 32 characters. Send it as `Authorization: Bearer <key>`. A key lists its scopes, and each operation below names the one it needs; a key may also be limited to one customer. An owner or a developer of the organization makes a key in the dashboard, under API keys, after a code sent to their e-mail. The key is shown once, when it is made. An owner or a developer can revoke it there, and a revoked key stops working within a minute.
- `Authorization` header (bearer token, required) — The access token of a person signed in to the dashboard, from the dashboard Cognito pool. Dashboard only, except that `POST /v1/customers`, `POST /v1/customers/{customer}/locations`, `POST /v1/locations/{location}/printers`, `PATCH /v1/printers/{printer}`, `DELETE /v1/printers/{printer}`, `POST /v1/printers/{printer}/rotate-secret` and `POST /v1/printers/{printer}/test-print` also take it, by role (an owner or a developer, with the organization named in `Tillcast-Organization`).

## Request

### Path parameters

- `printer` (string, required) — The printer's id.

### Query parameters

- `page` (enum, optional) — Which page to print: `basic`, the short page (the default), or `full`, the page with every barcode, every QR code and the images.
  - Allowed values: `basic`, `full`

### Headers

- `Idempotency-Key` (string, optional, nullable) — A string of 1 to 64 visible ASCII characters that identifies this request. A retry with the same key and the same `page` returns the first result (200, with `Idempotent-Replayed: true`) instead of queueing a second page. Keys are remembered for 24 hours.

## Response

### 200

A replay of an earlier request with the same Idempotency-Key.

- `client_reference_id` (string, required, nullable) — The id of this job in your own system, such as an order number, or `null`. Not unique: the same value can be on many jobs, and `GET /v1/jobs?client_reference_id=` lists every job that carries it (the last 7 days). No personal data.
- `completed_at` (string, required, nullable)
- `created_at` (string, required)
- `customer` (string, required)
- `delivered_at` (string, required, nullable)
- `expires_at` (string, required) — When the job stops being offered to the printer.
- `id` (string, required)
- `kind` (string, required) — `api` (yours), `welcome` (the first-connection receipt) or `test` (a test print: never billed).
- `location` (string, required)
- `metadata` (map from string to string, required, nullable)
- `object` (string, required)
- `printer` (string, required)
- `profile` (string, required, nullable) — The profile the document was rendered for: the id of a preset (`x-tillcast-profiles` lists them). A plain string and not an enum, so that a profile that is retired never breaks a client. `null` for a job that was queued as ready printer data and not rendered from a document, such as every job from before documents were rendered.
- `reason` (string, required, nullable) — Why the job did not print.
- `result_code` (string, required, nullable) — The printer's own status code for the job.
- `size_bytes` (long, required) — The size in bytes of what the printer is sent: the rendered document, after the transport step. Not the size of the document you sent.
- `status` (string, required) — `queued`, `delivered`, `printed`, `failed`, `expired` or `cancelled`.
- `transport` (string, required, nullable) — The transport step applied to the rendered bytes: its id and revision, such as `cloudprnt-star.1`. A later correction of a step changes new jobs only, and this tells which jobs were rendered with which. `null` where `profile` is.
- `warnings` (list of DocumentWarning, required) — What the renderer noticed in the document, in the order it happened: at most 21 (the first 20, and a `too_many_warnings` that says there were more). Always there, an empty list for a document with nothing to say. Kept with the job: a replay of the request and every later read return the same list.

### 201

The test job that was queued.

- `client_reference_id` (string, required, nullable) — The id of this job in your own system, such as an order number, or `null`. Not unique: the same value can be on many jobs, and `GET /v1/jobs?client_reference_id=` lists every job that carries it (the last 7 days). No personal data.
- `completed_at` (string, required, nullable)
- `created_at` (string, required)
- `customer` (string, required)
- `delivered_at` (string, required, nullable)
- `expires_at` (string, required) — When the job stops being offered to the printer.
- `id` (string, required)
- `kind` (string, required) — `api` (yours), `welcome` (the first-connection receipt) or `test` (a test print: never billed).
- `location` (string, required)
- `metadata` (map from string to string, required, nullable)
- `object` (string, required)
- `printer` (string, required)
- `profile` (string, required, nullable) — The profile the document was rendered for: the id of a preset (`x-tillcast-profiles` lists them). A plain string and not an enum, so that a profile that is retired never breaks a client. `null` for a job that was queued as ready printer data and not rendered from a document, such as every job from before documents were rendered.
- `reason` (string, required, nullable) — Why the job did not print.
- `result_code` (string, required, nullable) — The printer's own status code for the job.
- `size_bytes` (long, required) — The size in bytes of what the printer is sent: the rendered document, after the transport step. Not the size of the document you sent.
- `status` (string, required) — `queued`, `delivered`, `printed`, `failed`, `expired` or `cancelled`.
- `transport` (string, required, nullable) — The transport step applied to the rendered bytes: its id and revision, such as `cloudprnt-star.1`. A later correction of a step changes new jobs only, and this tells which jobs were rendered with which. `null` where `profile` is.
- `warnings` (list of DocumentWarning, required) — What the renderer noticed in the document, in the order it happened: at most 21 (the first 20, and a `too_many_warnings` that says there were more). Always there, an empty list for a document with nothing to say. Kept with the job: a replay of the request and every later read return the same list.

## Errors

### 400 Bad Request Error

The request is malformed or a parameter is invalid.

- `error` (ErrorObject, required)

### 401 Unauthorized Error

The key (or token) is missing or not valid.

- `error` (ErrorObject, required)

### 403 Forbidden Error

Not allowed.

- `error` (ErrorObject, required)

### 404 Not Found Error

There is no such object, or it is another organization's.

- `error` (ErrorObject, required)

### 409 Conflict Error

A conflict with the state of an object. The `code` is one of `customer_suspended`, `location_suspended`.

- `error` (ErrorObject, required)

### 422 Unprocessable Entity Error

The request is understood but refused. The `code` is one of `profile_mismatch`, `idempotency_key_reused`.

- `error` (ErrorObject, required)

### 429 Too Many Requests Error

The printer takes no test print now: it has taken as many test prints as it may, 5 in a minute and 3 waiting at a time (`rate_limited`), or its queue of 50 jobs is full (`queue_full`). `Retry-After` says when to try again.

- `error` (ErrorObject, required)

### 500 Internal Server Error

A problem on Tillcast's side.

- `error` (ErrorObject, required)

## Types

### DocumentWarning

Where the renderer did something other than the document says. A warning never changes what the renderer would print; it tells where it fell back quietly (a line with a stray brace is dropped, a column is made narrower, a character the printer cannot print becomes `?`). The message is a fixed text per code: it holds no part of the document, so it is safe to show or log.

- `code` (string, required) — A stable code to branch on. The ones known today are listed in `x-codes` of this schema; a new one can be added, so a client treats a code it does not know as a warning in general.
- `column` (integer, required, nullable) — The column on that line, from 1, counted in Unicode characters of the document (normalised to NFC); `null` when the document was rewritten at that place and the position cannot be told.
- `line` (integer, required) — The line of the document, from 1.
- `message` (string, required) — A sentence for a person. Do not parse it.

### ErrorObject

- `code` (string, required) — A stable code to branch on. The ones known today are listed in `x-codes` of this schema; a new one can be added, so a client treats a code it does not know by the HTTP status.
- `message` (string, required) — A sentence for a person. Do not parse it.
- `param` (string, required, nullable) — The request parameter the error is about, if one.
- `request_id` (string, required) — Quote it when you ask for help.
- `type` (string, required) — The kind of error: `invalid_request_error`, `authentication_error`, `permission_error`, `conflict_error`, `idempotency_error`, `rate_limit_error` or `api_error`.

## Examples

### Example 1

**Response**

```json
{
  "client_reference_id": "Invoice 2026/10/0815",
  "completed_at": null,
  "created_at": "2026-10-11T10:00:00Z",
  "customer": "cus_c3x9k2m3",
  "delivered_at": null,
  "expires_at": "2026-10-11T11:00:00Z",
  "id": "job_01M466JX008T2V5X7Z9C1E3G5H",
  "kind": "api",
  "location": "loc_01M42YMFP03Q1P9N7M5K3H1G0F",
  "metadata": {
    "booking": "4711"
  },
  "object": "job",
  "printer": "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
  "profile": "star-starprnt-utf8-80mm",
  "reason": null,
  "result_code": null,
  "size_bytes": 1194,
  "status": "queued",
  "transport": "cloudprnt-star.1",
  "warnings": [
    {
      "code": "line_dropped_stray_brace",
      "column": 5,
      "line": 3,
      "message": "The line contains a stray brace and prints nothing."
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print"

querystring = {"page":"full"}

headers = {
    "Idempotency-Key": "test-print-4711",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full';
const options = {
  method: 'POST',
  headers: {'Idempotency-Key': 'test-print-4711', Authorization: 'Bearer <token>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Idempotency-Key", "test-print-4711")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = 'test-print-4711'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full")
  .header("Idempotency-Key", "test-print-4711")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Idempotency-Key' => 'test-print-4711',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "test-print-4711");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Idempotency-Key": "test-print-4711",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Example 2

**Response**

```json
{
  "client_reference_id": "Invoice 2026/10/0815",
  "completed_at": null,
  "created_at": "2026-10-11T10:00:00Z",
  "customer": "cus_c3x9k2m3",
  "delivered_at": null,
  "expires_at": "2026-10-11T11:00:00Z",
  "id": "job_01M466JX008T2V5X7Z9C1E3G5H",
  "kind": "api",
  "location": "loc_01M42YMFP03Q1P9N7M5K3H1G0F",
  "metadata": {
    "booking": "4711"
  },
  "object": "job",
  "printer": "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
  "profile": "star-starprnt-utf8-80mm",
  "reason": null,
  "result_code": null,
  "size_bytes": 1194,
  "status": "queued",
  "transport": "cloudprnt-star.1",
  "warnings": [
    {
      "code": "line_dropped_stray_brace",
      "column": 5,
      "line": 3,
      "message": "The line contains a stray brace and prints nothing."
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print"

querystring = {"page":"full"}

headers = {
    "Idempotency-Key": "test-print-4711",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full';
const options = {
  method: 'POST',
  headers: {'Idempotency-Key': 'test-print-4711', Authorization: 'Bearer <token>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Idempotency-Key", "test-print-4711")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = 'test-print-4711'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full")
  .header("Idempotency-Key", "test-print-4711")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Idempotency-Key' => 'test-print-4711',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "test-print-4711");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Idempotency-Key": "test-print-4711",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```