Skip to navigation

Provision a venue from your software

Make a customer, a location and a printer through the API, hand the printer URL to the venue and check the first page.
View as Markdown
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. If your software only prints on printers that exist already, you need Integrate a point of sale and not this page.

The steps

#StepCallScope of the keyWho
1Find or create the customerGET /v1/customers?client_reference_id=, POST /v1/customerscustomers:read, customers:writeYour software
2Find or create the locationGET /v1/locations?client_reference_id=, POST /v1/customers/{customer}/locationscustomers:read, customers:writeYour software
3Create the printerGET /v1/printers?client_reference_id=, POST /v1/locations/{location}/printersprinters:read, printers:writeYour software
4Hand the printer URL to the venue and type it into the printerNoneNoneA person
5Wait until the printer is onlineGET /v1/printers/{printer}printers:readYour software
6Print the first test pagePOST /v1/printers/{printer}/test-printjobs:writeYour 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.
  • 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. If your ids are meant to be unique, stop and ask a person instead, as the sample below does. See Your own IDs.
  • 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.

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.

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"}'
{
"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.

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"}'
{
"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.

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"}'
{
"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.

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.

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.

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 happenedWhat to do
No answer, or a 5xx, within 24 hoursSend 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 anyoneRotate 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 alreadyDo 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 laterThe 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 answerCall 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.

  • 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 or Set up an Epson printer, and to the Printer 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.

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

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.

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