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

# Provision a venue from your software

> Set up a venue through the Tillcast API: customer, location and printer with your own ids, safe retries, a lost answer, the printer URL and the first test page.

> **These calls change the live account**
>
> Every call on this page acts on the live API: it creates customers and printers, and a test page prints on real paper. Run it only with a key you were given for this purpose. An agent must not run it unless the owner of the key asked and named the venue.

This page is for a software vendor, such as a property management or booking system, that sets printers up for its own customers: a hotel group, one hotel of the group, a printer at its front desk. Tillcast calls your company the **organization**, the hotel group a **customer**, the hotel a **location** and the device a **printer**. See the [concepts overview](/concepts/overview). If your software only prints on printers that exist already, you need [Integrate a point of sale](/integrate-a-pos) and not this page.

## The steps

| # | Step                                                           | Call                                                                                | Scope of the key                    | Who                                         |
| - | -------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------- |
| 1 | Find or create the customer                                    | `GET /v1/customers?client_reference_id=`, `POST /v1/customers`                      | `customers:read`, `customers:write` | Your software                               |
| 2 | Find or create the location                                    | `GET /v1/locations?client_reference_id=`, `POST /v1/customers/{customer}/locations` | `customers:read`, `customers:write` | Your software                               |
| 3 | Create the printer                                             | `GET /v1/printers?client_reference_id=`, `POST /v1/locations/{location}/printers`   | `printers:read`, `printers:write`   | Your software                               |
| 4 | Hand the printer URL to the venue and type it into the printer | None                                                                                | None                                | **A person**                                |
| 5 | Wait until the printer is online                               | `GET /v1/printers/{printer}`                                                        | `printers:read`                     | Your software                               |
| 6 | Print the first test page                                      | `POST /v1/printers/{printer}/test-print`                                            | `jobs:write`                        | Your software, or a person in the dashboard |

## Keys

Steps 1 to 5 need the scopes of the **Installer** preset: `customers:read`, `customers:write`, `printers:read` and `printers:write`. That key cannot print and cannot read jobs, so it is the right key for provisioning and a poor one to leave in a till. Step 6 needs `jobs:write`, which the Installer preset does not have. Use the key your point of sale already holds (the **Printing** preset), or let a person press **Test print** on the printer's page in the dashboard.

* The key must cover the whole organization. A key limited to one customer cannot create customers (`403 restricted_key`).
* A person makes every key, in the dashboard, under **API keys**, after a six-digit code that Tillcast e-mails to them. A key cannot be created through the API, and neither can an organization. See [Authentication and API keys](/api/authentication).
* Keep the key in an environment variable on your server, never in a browser or an app.

## Your own ids and safe retries

Put the id each object has in your own software in its `client_reference_id`: the account of the hotel group, the code of the hotel, the code of the printer. It is not unique and Tillcast never refuses it, so it does not stop you creating a second object. Two habits do that:

* **Find before you create.** Each list takes `client_reference_id` and answers with every object that carries the value. An unknown value is an empty list. A search normally answers in one page with `has_more: false`. When very many objects share a value, a search can answer a short page, even an empty one, with `has_more: true` and a `next_cursor`. That is not "nothing found": follow the cursor until `has_more` is `false` before you decide that nothing exists, see [Pagination](/api/pagination#searches-can-answer-a-short-page). If your ids are meant to be unique, stop and ask a person instead, as the sample below does. See [Your own IDs](/concepts/client-reference-id).
* **Send an `Idempotency-Key` with every create.** A retry with the same key and the same body answers the same object (`200` with `Idempotent-Replayed: true`), and nothing new is made. A key is remembered for 24 hours. The key is shared by all kinds of create of your organization, so use a different key for each one: the same key on a customer and on a location is `422 idempotency_key_reused`. A key made from your own ids and the kind of object works well, such as `venue-acct-1042-prop-17-location`. **Every id inside a key must be unique across all your venues.** The key belongs to the whole organization, and a printer called `front-desk` exists in every hotel: if the printers of two hotels both use the key `venue-front-desk-printer`, the second create is `422 idempotency_key_reused`, so put the account and the code of the hotel into it. A hotel code that is only unique inside one account is not enough. A key is 1 to 64 visible ASCII characters, and a `client_reference_id` can be 128: with long ids the key can pass 64 and the create is `400 idempotency_key_invalid`, so shorten the ids in the key, or use a short hash of them.

## Make the customer, the location and the printer

The ids in the answers are made up. Replace them with yours.

```bash wordWrap
export API=https://api.tillcast.com

curl "$API/v1/customers?client_reference_id=acct-1042" \
  -H "Authorization: Bearer $TILLCAST_PROVISIONING_KEY" \
  -H "Tillcast-Version: 2026-10-01"
```

When the list is empty and `has_more` is `false`, create the customer. The answer is `201`.

```bash wordWrap
curl $API/v1/customers \
  -H "Authorization: Bearer $TILLCAST_PROVISIONING_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: venue-acct-1042-customer" \
  -H "Content-Type: application/json" \
  -d '{"name": "Baltic Hotels Sp. z o.o.", "client_reference_id": "acct-1042"}'
```

```json wordWrap
{
  "id": "cus_c3x9k2m3",
  "object": "customer",
  "name": "Baltic Hotels Sp. z o.o.",
  "client_reference_id": "acct-1042",
  "state": "active",
  "mode": "live",
  "location_count": 0,
  "printer_count": 0,
  "created_at": "2026-10-11T09:15:00Z"
}
```

The id of a customer is `cus_` and its 8-character code, which becomes the host of its printers' URLs. Make the location under it.

```bash wordWrap
curl $API/v1/customers/cus_c3x9k2m3/locations \
  -H "Authorization: Bearer $TILLCAST_PROVISIONING_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: venue-acct-1042-prop-17-location" \
  -H "Content-Type: application/json" \
  -d '{"name": "Hotel Gdansk Old Town", "client_reference_id": "prop-17", "timezone": "Europe/Warsaw"}'
```

```json wordWrap
{
  "id": "loc_01M42YMFP03Q1P9N7M5K3H1G0F",
  "object": "location",
  "customer": "cus_c3x9k2m3",
  "name": "Hotel Gdansk Old Town",
  "client_reference_id": "prop-17",
  "state": "active",
  "printer_count": 0,
  "created_at": "2026-10-11T09:20:00Z",
  "timezone": "Europe/Warsaw"
}
```

Now the printer. Say the paper it prints on, `58mm` or `80mm`, and name no `vendor`, `profile`, `print_options` or `allowed_mac`. Tillcast then reads the maker from the printer's first connection and a Star's width from what the Star reports, so your software does not have to know which printer the venue bought. See [Add a printer by its paper width](/printers/profiles#add-a-printer-by-its-paper-width).

```bash wordWrap
curl $API/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers \
  -H "Authorization: Bearer $TILLCAST_PROVISIONING_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: venue-acct-1042-prop-17-front-desk-printer" \
  -H "Content-Type: application/json" \
  -d '{"name": "Front desk", "client_reference_id": "front-desk", "paper_width": "80mm"}'
```

```json wordWrap
{
  "id": "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
  "object": "printer",
  "customer": "cus_c3x9k2m3",
  "location": "loc_01M42YMFP03Q1P9N7M5K3H1G0F",
  "name": "Front desk",
  "client_reference_id": "front-desk",
  "vendor": "star",
  "vendor_source": "default",
  "brand": null,
  "model": null,
  "mode": "live",
  "status": "never_connected",
  "connection": "never_connected",
  "condition": [],
  "status_code": null,
  "mac": null,
  "allowed_mac": null,
  "pending_jobs": 0,
  "auth_error_at": null,
  "reported_mac": null,
  "profile": "star-starprnt-utf8-80mm",
  "profile_source": "default",
  "paper_width": "80mm",
  "detection": "pending",
  "welcome_print": true,
  "created_at": "2026-10-11T09:25:00Z",
  "url": "https://c3x9k2m3.print.tillcast.com/r4twh8nca3bx5dfn"
}
```

The answer reads `"vendor": "star"` with `"vendor_source": "default"` and `"detection": "pending"` until the printer first connects: its maker is not known yet. Then `vendor` is `star` or `epson`, `vendor_source` is `detected` and `detection` is `done`, or `undetected` for a Star whose report cannot be used. Until then:

* A `PATCH` that names `profile`, `print_options` or `allowed_mac`, or turns `welcome_print` on, is `409 printer_not_identified`. Wait for the first connection.
* A page queued for it is made for a Star. If the printer turns out to be an Epson, the page ends `failed` with the reason `rendered_for_other_vendor`, and nothing prints.
* An Epson reports no line width, so its profile is the default of its paper (`profile_source` `default`) until a person checks the width on paper in the dashboard, or you set its `profile` with a `PATCH` once it has connected.

If you know the maker, name it instead, with the `profile` that matches the paper. Nothing is detected then: the answer reads `vendor_source` `explicit`, `paper_width` `null` and `detection` `done`. The `vendor` cannot be changed afterwards, and a profile of the other maker is refused. Use one call or the other for a printer, not both, and a different `Idempotency-Key`. See [Profiles and print options](/printers/profiles).

```bash wordWrap
curl $API/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers \
  -H "Authorization: Bearer $TILLCAST_PROVISIONING_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: venue-acct-1042-prop-17-front-desk-printer-named" \
  -H "Content-Type: application/json" \
  -d '{"name": "Front desk", "client_reference_id": "front-desk", "vendor": "star", "profile": "star-starprnt-utf8-80mm"}'
```

The `url` is in the answer of a create **only**. A replay of the call, the same key and the same body, answers `200` with `url: null`. A read and a list of printers have no `url` at all, so test for a missing `url` and not for `null`.

The same flow in TypeScript, for a server that provisions on demand. It returns the printer, and the URL when this call made the printer. It stops and asks for a person when two objects carry the same id, because Tillcast does not forbid that, and when a search says `has_more`.

The SDK packages that are published today have no `paper_width` field, so this sample names the maker and the profile.

Set `TILLCAST_BASE_URL` to `https://api.tillcast.com` on purpose. An SDK client with no base URL calls the live API, and `process.env.NAME!` only silences the type checker, so the sample stops when a variable is missing. See [SDKs](/getting-started/sdks).

```ts
import { Tillcast, TillcastClient } from "@tillcast/sdk";

function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is not set`);
  return value;
}

const client = new TillcastClient({
  token: requireEnv("TILLCAST_PROVISIONING_KEY"),
  baseUrl: requireEnv("TILLCAST_BASE_URL"),
});

interface Venue {
  account: string;
  property: string;
  device: string;
  groupName: string;
  hotelName: string;
  printerName: string;
  // What the venue bought. The vendor cannot be changed after the printer is made, so never default it.
  vendor: Tillcast.PrinterVendor;
  profile: Tillcast.PrinterProfile;
}

// An empty page with has_more true is not "nothing found", and two matches are not
// for a program to choose between: both stop here.
function justOne<T>(page: { data: T[]; has_more: boolean }, what: string): T | undefined {
  if (page.has_more || page.data.length > 1) {
    throw new Error(`The search for ${what} is not a single clean answer: ask a person`);
  }
  return page.data[0];
}

export async function provision(venue: Venue) {
  const customer =
    justOne(await client.customers.list({ client_reference_id: venue.account }), "customers") ??
    (await client.customers.create({
      "Idempotency-Key": `venue-${venue.account}-customer`,
      name: venue.groupName,
      client_reference_id: venue.account,
    }));

  const location =
    justOne(
      await client.locations.list({ customer: customer.id, client_reference_id: venue.property }),
      "locations",
    ) ??
    (await client.locations.create({
      customer: customer.id,
      "Idempotency-Key": `venue-${venue.account}-${venue.property}-location`,
      name: venue.hotelName,
      client_reference_id: venue.property,
    }));

  const existing = justOne(
    await client.printers.list({ location: location.id, client_reference_id: venue.device }),
    "printers",
  );
  if (existing) return { printer: existing, url: null };

  const created = await client.printers.create({
    location: location.id,
    "Idempotency-Key": `venue-${venue.account}-${venue.property}-${venue.device}-printer`,
    name: venue.printerName,
    vendor: venue.vendor,
    profile: venue.profile,
    client_reference_id: venue.device,
  });
  // `url` is null when this was a replay of a call whose answer you lost: see the next section.
  return { printer: created, url: created.url };
}
```

## When an answer is lost

A create can work while its answer never reaches you. For a customer or a location the cure is the retry: send the same request with the same key and the same body, and you get the object. The SDKs do not retry a timeout or a dropped connection for you, see [Retry safely](/create-a-print-job#retry-safely).

For a printer the object is not enough, because the URL was in the lost `201`. Decide by **whether the URL has been seen**:

| What happened                          | What to do                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No answer, or a `5xx`, within 24 hours | Send the same create again with the same key and the same body. If the first call never arrived, this one is the first: `201` with the URL. If the first call worked, you get the printer with `200`, `Idempotent-Replayed: true` and `url: null`, and the URL is only in the answer you lost: go on with the next row. (It can also answer `503 printer_domain_unavailable`, even though the first call worked: wait and send it again) |
| The URL was never shown to anyone      | Rotate the secret: `POST /v1/printers/{printer}/rotate-secret` (scope `printers:write`). The answer holds a new URL, once, and the lost one stops working. This is also how to get the URL of any printer again                                                                                                                                                                                                                          |
| The URL was shown or typed in already  | Do **not** rotate to repair a lost answer. Rotating stops the printer until the new URL is typed in. Rotate only when the URL is lost or has leaked, and then type the new one into the printer                                                                                                                                                                                                                                          |
| More than 24 hours later               | The key is forgotten, and a create with a new key would make a second printer. Search for `client_reference_id` first, and rotate the one you find if the URL was never seen                                                                                                                                                                                                                                                             |
| The rotate call itself had no answer   | Call it again. A rotation has no `Idempotency-Key`, and every call makes a new secret, which is harmless while nobody has the lost URL                                                                                                                                                                                                                                                                                                   |

A printer whose `status` is `online`, `offline`, `wrong_host` or `mac_mismatch` has been reached by a device that used the URL, so treat the URL as seen. `never_connected` means that no device has used it. `customer_suspended` and `location_suspended` come first whatever the printer did, so they tell you nothing about the URL: ask the person who installed the printer before you rotate the secret.

## Give the URL to the venue

The printer URL is a **password**: anyone who holds the whole URL can poll as that printer and download its receipts. See [Printer URL](/concepts/printer-url).

* Show it once, on a screen of yours behind your own sign-in, or hand it to the installer who types it into the printer, and let it go. Do not store it, log it, put it in a ticket or a chat message, or send it in an e-mail that others read. When it is lost, rotate the secret.
* The person types it into the printer's settings and restarts the printer. A Star takes it in its CloudPRNT settings and an Epson in its Server Direct Print settings: send them to [Set up a Star printer](/printers/star-setup) or [Set up an Epson printer](/printers/epson-setup), and to the [Printer setup checklist](/printers/setup-checklist). The printer needs outgoing HTTPS and nothing else on the network.

## Wait until the printer is online

Read the printer and look at `status` and `last_seen_at`.

```bash wordWrap
curl $API/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0 \
  -H "Authorization: Bearer $TILLCAST_PROVISIONING_KEY" \
  -H "Tillcast-Version: 2026-10-01"
```

* `status` goes from `never_connected` to `online` within a poll or two, about 5 to 10 seconds, after the URL is typed in and the printer is restarted. A `brand` and `model` appear for a Star. A printer added by its paper width also settles: `vendor_source` becomes `detected`, and `detection` goes from `pending` to `done`, or to `undetected` when a Star reports a paper that Tillcast cannot print on yet. A Star answers the question about its paper at its first connection, so this can take a poll longer. Ask again every few seconds for a few minutes, then stop and tell the installer.
* `wrong_host` means the printer called a host that is not its own, for example a typo in the customer code, and `mac_mismatch` that a device other than the allowed one connected: compare the URL typed in with the one you handed over. See [Troubleshooting](/printers/troubleshooting).
* `last_seen_at` is written at most once a minute, and `online` is **not** cleared when the printer is switched off. For a printer that was online some time ago, judge by how old `last_seen_at` is.
* There is no webhook that tells you a printer connected: webhooks are planned and do not exist. Poll.

## The first test page

A Star that connects for the first time prints a welcome receipt by itself, with the names of your location and printer, so the installer sees at once that the URL was typed correctly. An Epson prints none. See [First connection](/printers/first-connection).

Queue a test page **after** the printer is online, with a key that has `jobs:write`, or press **Test print** in the dashboard. On a Star a test page queued before the first connection takes the place of the welcome receipt, and it is offered to the printer for one hour only. For a printer added by its paper width, a page queued before the first connection is made for a Star and fails with `rendered_for_other_vendor` if the printer is an Epson.

```bash wordWrap
curl -X POST $API/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: venue-acct-1042-prop-17-front-desk-test-1"
```

The answer is a job of kind `test`. A printer takes at most 5 test prints in any minute and 3 waiting at a time. A test print queued again and again before the printer is online fills those three places, and the fourth is `429 rate_limited` with `Retry-After: 30` until the printer prints them or an hour has passed, so connect the printer first. See [First connection](/printers/first-connection#test-print). The paper decides whether it worked: someone has to look at it.

## What only a person can do

Do not try to automate these, and an agent must not try:

* Sign up, create the organization and make the API keys. Both need a person and an e-mailed code.
* Put the printer in the venue, connect it to the network, and type the printer URL into its settings. Restart it.
* Look at the paper from the welcome receipt or the test page.
* Check the line width of an Epson that was added by its paper width: the sheet and its code are in the dashboard. Or set its `profile` through the API once it has connected.
* Replace a printer or reset it. A factory reset erases the address typed into the printer, so you rotate the secret and type the new URL in.

## What is not there

* **There is no sandbox.** Every key is live, and the only way to see a printer work is a real printer. Test your provisioning code against a fake client of your own.
* **There are no webhooks.** Poll the printer, as above.

## Remove a venue

Removing a venue is done in the other order. Clear the address in the printer first, because a printer keeps polling an address that no longer exists. Then delete the printer (`DELETE /v1/printers/{printer}`, which cancels its waiting jobs), then the location, then the customer. A customer that still has locations, or a location that still has printers, is `409 not_empty`. To stop printing for a customer without deleting anything, use [Suspension and pause](/concepts/suspension).