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

# Add a printer

POST https://api.tillcast.com/v1/locations/{location}/printers
Content-Type: application/json

Adds a printer to a location and returns the URL to type into the
printer's CloudPRNT server field. The URL holds the printer's secret and
is shown only in this answer: keep it, or rotate the secret later to get
a new one. The customer and the location must be active. `allowed_mac` names
the one device that may use the URL: an extra safeguard for this one
address, not authentication. Without it, any device that holds the URL is
accepted, and a printer is not tied to the first device that connects. A MAC
address can be read from the label of a printer, but use the MAC the printer
reports (`mac` once it has connected). The brand and the model are read from
the printer after it has connected, and cannot be sent. A printer is a Star
printer unless `vendor` says `epson`, an Epson printer that every
organization may make and on which documents and the test page print (see
`vendor`); its URL goes into the printer's Server Direct Print setting. Send
`paper_width` and no `vendor`, `profile`, `print_options` or `allowed_mac`
and the maker is read from the printer's first connection, and a Star's
width from what it reports (see `paper_width`).
`profile` and `print_options` say how documents are printed on the printer
(the paper width in characters, the text encoding, the command set); left
out, the default of the `vendor` is used, and the answer says which one
that is. They are checked before anything is made: a mistake in either is a
`422` and no printer. 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 its URL is shown once
there too. A person is refused with `permission_denied` (a viewer),
`organization_suspended`, `organization_required` (no header) or
`resource_missing` (not a member of that organization).

**Scope:** `printers:write`.

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

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

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

### 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 body returns the first result (200, with `Idempotent-Replayed: true`) instead of making a second object; the same key with a different body is an error (422). Keys are remembered for 24 hours.

### Body (application/json)

This endpoint expects a CreatePrinter.

- `name` (string, required) — 1 to 64 characters.
- `allowed_mac` (string, optional, nullable) — The one device that may use the printer's URL, as a MAC address: twelve hexadecimal digits, with `:` or `-` between the pairs or none. Left out, or `null`, any device that holds the URL is accepted. With a device named, the MAC address the device reports must be this one, and a device that reports none is refused too: it gets a bare `403`, and the status can become `mac_mismatch` when the refused device named itself and the printer has been quiet for a while. This is an extra safeguard for this one address, not authentication: the secret in the URL is the credential, a MAC address is printed on the printer's label, and its first three bytes name the maker. A MAC address can be read from the label, but use the MAC the printer reports (`mac` of the printer once it has connected): some models print the Wi-Fi MAC on the label and report the Ethernet one. It needs a printer whose firmware reports its MAC address. An all-zero, broadcast or multicast address is refused. It is stored and returned in lower case with colons, and the same address may be named on any number of printers. A printer made with `vendor` `epson` reports no MAC address, so naming a device for it is refused (`400 parameter_invalid`).
- `client_reference_id` (string, optional, nullable) — The id of this printer in your own system, 1 to 128 characters. It is not unique and never refused for being used already; search for it with `GET /v1/printers?client_reference_id=` before you create when you need to find the printer you made earlier, and send an `Idempotency-Key` so that a retried create makes one printer.
- `domain` (string, optional, nullable) — The printer domain to make the URL on: `print.tillcast.com`, or a domain that Tillcast has set up and activated for your organization. Left out or `null`, the printer gets the domain Tillcast has chosen for your organization, which is `print.tillcast.com` unless it has set up one of its own for you. Any other value is `400 parameter_invalid` naming `domain`, with the same words whether or not that domain exists. The host of the URL is always `<code>.<domain>` with the code Tillcast gives the customer: nothing you send makes a part of it. `domain` of the printer says which domain it has; it never changes.
- `paper_width` (enum, optional, nullable)
  - Allowed values: `58mm`, `80mm`
- `print_options` (PrintOptions, optional, nullable) — What can be set on top of a profile, each field optional. A field left out keeps the profile's own value. The ranges are checked when the printer is made or changed: a value outside its range, or an `encoding` the profile does not take, is `422 print_options_invalid` naming the field.
- `profile` (enum, optional, nullable) — The id of a profile a printer can be set to. `x-tillcast-profiles` of the contract says what each is for and how far it has been checked on a real printer (`evidence`).
  - Allowed values: `star-starprnt-utf8-80mm`, `star-starprnt-utf8-58mm`, `star-starprnt-cp852-80mm`, `star-starprnt-cp852-58mm`, `epson-80mm-48`, `epson-80mm-42`, `epson-58mm-35`, `epson-58mm-30`, `epson-legacy-80mm-42`
- `vendor` (enum, optional, nullable)
  - Allowed values: `star`, `epson`
- `welcome_print` (boolean, optional, nullable) — Print a welcome receipt when the printer first connects. On by default (the organization can switch it off for all its printers). A printer made with `vendor` `epson` prints none, whatever this says.

## Response

### 200

A replay of an earlier request with the same Idempotency-Key. `url` is null.

- `allowed_mac` (string, required, nullable) — The one device allowed to use this printer's address; `null` means that any device that holds the address is accepted. See `allowed_mac` of the request that sets it.
- `auth_error_at` (string, required, nullable) — When a refused request last left a hint: `wrong_host` (the host is not the printer's) or `mac_mismatch` (the address names an allowed device and another device connected). `null` when there is none.
- `brand` (string, required, nullable) — Read from the printer itself; `null` until it has connected and answered. It cannot be set through the API. Text the printer sent, kept to ASCII letters, digits and `. _ - + ( ) /`: a claim of whoever holds the printer's address, not verified. Treat it as untrusted text.
- `client_reference_id` (string, required, nullable) — The id of this printer in your own system, such as `kitchen-1`, or `null`. Not unique: the same value can be on many objects, and `GET /v1/printers?client_reference_id=` lists every printer that carries it. `null` for every printer made before the field existed.
- `condition` (list of string, required) — What the printer reports is wrong: `paper_low`, `paper_out`, `cover_open`, `jam` or `error`.
- `connection` (string, required) — `never_connected`, `connected` or `disconnected` (the printer has connected and has not polled for about 4 minutes: its `status` is `offline` unless a suspension or a refused request comes first).
- `created_at` (string, required)
- `customer` (string, required)
- `id` (string, required)
- `location` (string, required)
- `mac` (string, required, nullable) — The MAC address the printer reported on its last accepted poll. For display only: it never addresses or authenticates a printer, and it is a claim by whoever polled with the address secret, not a verified fact. `null` until the first poll, and for a printer that does not report one.
- `mode` (string, required)
- `model` (string, required, nullable) — Read from the printer itself; `null` until it has connected and answered. It cannot be set through the API. Text the printer sent, kept to ASCII letters, digits and `. _ - + ( ) /`: a claim of whoever holds the printer's address, not verified. Treat it as untrusted text.
- `name` (string, required)
- `object` (string, required)
- `pending_jobs` (integer, required) — Jobs waiting for the printer that have not expired.
- `reported_mac` (string, required, nullable) — While `status` is `mac_mismatch`: the MAC address of the device that was refused, taken from the refused request. Also a claim: compare it with the label of your printer before you allow it. `null` otherwise.
- `status` (string, required) — `never_connected`, `online`, `offline` (the printer has connected and has not polled for about 4 minutes), `wrong_host`, `mac_mismatch` (the address names an allowed device and another device connected), `customer_suspended` or `location_suspended`.
- `status_code` (string, required, nullable) — The printer's last status code, such as `200 OK`.
- `vendor` (string, required) — `star` or `epson`: set when the printer is made and never changed (see `vendor` of the request that adds a printer), with one exception: a printer made with `paper_width` and no maker reads `star` until its first connection names the maker, once (`vendor_source` says which case it is).
- `url` (string, required, nullable) — The URL to type into the printer's server setting: the CloudPRNT server field of a `star` printer, the Server Direct Print setting of an `epson` printer (see `vendor`). `null` when the answer is a replay of an earlier request with the same Idempotency-Key, because the URL is shown only once: rotate the secret for a new one.
- `detection` (string, optional, nullable) — What is left for the server to settle on the printer. `pending`: it was made with `paper_width` and nothing that names its maker, and has not been settled yet (its maker is set by its first connection, and a Star's width by what the printer reports). `undetected`: a Star reported something Tillcast cannot print on yet (Star Line mode, 104 mm paper), or nothing usable, so it prints with the default of its paper. `done`: every other printer, one made before this field included. A plain string and not an enum. Only in the answer to a single printer, not in a list.
- `domain` (string, optional, nullable) — The printer domain the printer's URL is on: `print.tillcast.com`, or a domain that Tillcast has set up for your organization. The host of the URL is `<code of the customer>.<domain>`: the code is Tillcast's own random code of the customer (the part of the customer's id after `cus_`), never an id of yours. It is recorded when the printer is made and kept when its secret is replaced. Only in the answer to a single printer, not in a list.
- `last_seen_at` (string, optional, nullable) — When the printer last polled us. Only in the answer to a single printer.
- `paper_width` (string, optional, nullable) — The paper the printer was made for: `58mm`, `80mm`, or `null` when it was made without `paper_width`. Set when the printer is made and never changed. Only in the answer to a single printer, not in a list.
- `print_options` (PrintOptions, optional, nullable) — What can be set on top of a profile, each field optional. A field left out keeps the profile's own value. The ranges are checked when the printer is made or changed: a value outside its range, or an `encoding` the profile does not take, is `422 print_options_invalid` naming the field.
- `profile` (string, optional, nullable) — The profile documents are rendered for (command set, paper width in characters and text encoding): the id of a preset, the one set with `profile` or, while none is set, the default of the printer's `vendor` (`star-starprnt-utf8-80mm` for a `star` printer, `epson-80mm-48` for an `epson` one). It is the profile the printer prints with, also for a printer made before profiles could be chosen, and, for a printer made with `paper_width` and no profile, the one detected from the printer or confirmed on paper (`profile_source` says which). A plain string and not an enum, so that a profile that is retired never breaks a client; `x-tillcast-profiles` of the contract lists the ones a printer can be set to. Only in the answer to a single printer, not in a list.
- `profile_source` (string, optional, nullable) — Where `profile` comes from. `default`: nobody chose, so the default of the paper and the maker applies. `detected`: a Star's own report chose the width. `confirmed`: a calibration code chose it. `explicit`: a request or an edit named it, and every printer made before this field existed. A plain string and not an enum, so that a word added later never breaks a client. Only in the answer to a single printer, not in a list.
- `vendor_source` (string, optional, nullable) — Where `vendor` comes from. `default`: no maker was named, so the printer reads `star` until its first connection names the maker. `detected`: the first connection decided it. `explicit`: the request that made the printer named it, or the printer was made without `paper_width`, or before that field existed: the server never changes an explicit maker. A plain string and not an enum, so that a word added later never breaks a client. Only in the answer to a single printer, not in a list.
- `welcome_print` (boolean, optional, nullable) — Whether the printer prints a welcome receipt on its first connection. An `epson` printer prints none: it reads `false`. Only in the answer to a single printer.

### 201

The printer that was made, with the URL to type into it.

- `allowed_mac` (string, required, nullable) — The one device allowed to use this printer's address; `null` means that any device that holds the address is accepted. See `allowed_mac` of the request that sets it.
- `auth_error_at` (string, required, nullable) — When a refused request last left a hint: `wrong_host` (the host is not the printer's) or `mac_mismatch` (the address names an allowed device and another device connected). `null` when there is none.
- `brand` (string, required, nullable) — Read from the printer itself; `null` until it has connected and answered. It cannot be set through the API. Text the printer sent, kept to ASCII letters, digits and `. _ - + ( ) /`: a claim of whoever holds the printer's address, not verified. Treat it as untrusted text.
- `client_reference_id` (string, required, nullable) — The id of this printer in your own system, such as `kitchen-1`, or `null`. Not unique: the same value can be on many objects, and `GET /v1/printers?client_reference_id=` lists every printer that carries it. `null` for every printer made before the field existed.
- `condition` (list of string, required) — What the printer reports is wrong: `paper_low`, `paper_out`, `cover_open`, `jam` or `error`.
- `connection` (string, required) — `never_connected`, `connected` or `disconnected` (the printer has connected and has not polled for about 4 minutes: its `status` is `offline` unless a suspension or a refused request comes first).
- `created_at` (string, required)
- `customer` (string, required)
- `id` (string, required)
- `location` (string, required)
- `mac` (string, required, nullable) — The MAC address the printer reported on its last accepted poll. For display only: it never addresses or authenticates a printer, and it is a claim by whoever polled with the address secret, not a verified fact. `null` until the first poll, and for a printer that does not report one.
- `mode` (string, required)
- `model` (string, required, nullable) — Read from the printer itself; `null` until it has connected and answered. It cannot be set through the API. Text the printer sent, kept to ASCII letters, digits and `. _ - + ( ) /`: a claim of whoever holds the printer's address, not verified. Treat it as untrusted text.
- `name` (string, required)
- `object` (string, required)
- `pending_jobs` (integer, required) — Jobs waiting for the printer that have not expired.
- `reported_mac` (string, required, nullable) — While `status` is `mac_mismatch`: the MAC address of the device that was refused, taken from the refused request. Also a claim: compare it with the label of your printer before you allow it. `null` otherwise.
- `status` (string, required) — `never_connected`, `online`, `offline` (the printer has connected and has not polled for about 4 minutes), `wrong_host`, `mac_mismatch` (the address names an allowed device and another device connected), `customer_suspended` or `location_suspended`.
- `status_code` (string, required, nullable) — The printer's last status code, such as `200 OK`.
- `vendor` (string, required) — `star` or `epson`: set when the printer is made and never changed (see `vendor` of the request that adds a printer), with one exception: a printer made with `paper_width` and no maker reads `star` until its first connection names the maker, once (`vendor_source` says which case it is).
- `url` (string, required, nullable) — The URL to type into the printer's server setting: the CloudPRNT server field of a `star` printer, the Server Direct Print setting of an `epson` printer (see `vendor`). `null` when the answer is a replay of an earlier request with the same Idempotency-Key, because the URL is shown only once: rotate the secret for a new one.
- `detection` (string, optional, nullable) — What is left for the server to settle on the printer. `pending`: it was made with `paper_width` and nothing that names its maker, and has not been settled yet (its maker is set by its first connection, and a Star's width by what the printer reports). `undetected`: a Star reported something Tillcast cannot print on yet (Star Line mode, 104 mm paper), or nothing usable, so it prints with the default of its paper. `done`: every other printer, one made before this field included. A plain string and not an enum. Only in the answer to a single printer, not in a list.
- `domain` (string, optional, nullable) — The printer domain the printer's URL is on: `print.tillcast.com`, or a domain that Tillcast has set up for your organization. The host of the URL is `<code of the customer>.<domain>`: the code is Tillcast's own random code of the customer (the part of the customer's id after `cus_`), never an id of yours. It is recorded when the printer is made and kept when its secret is replaced. Only in the answer to a single printer, not in a list.
- `last_seen_at` (string, optional, nullable) — When the printer last polled us. Only in the answer to a single printer.
- `paper_width` (string, optional, nullable) — The paper the printer was made for: `58mm`, `80mm`, or `null` when it was made without `paper_width`. Set when the printer is made and never changed. Only in the answer to a single printer, not in a list.
- `print_options` (PrintOptions, optional, nullable) — What can be set on top of a profile, each field optional. A field left out keeps the profile's own value. The ranges are checked when the printer is made or changed: a value outside its range, or an `encoding` the profile does not take, is `422 print_options_invalid` naming the field.
- `profile` (string, optional, nullable) — The profile documents are rendered for (command set, paper width in characters and text encoding): the id of a preset, the one set with `profile` or, while none is set, the default of the printer's `vendor` (`star-starprnt-utf8-80mm` for a `star` printer, `epson-80mm-48` for an `epson` one). It is the profile the printer prints with, also for a printer made before profiles could be chosen, and, for a printer made with `paper_width` and no profile, the one detected from the printer or confirmed on paper (`profile_source` says which). A plain string and not an enum, so that a profile that is retired never breaks a client; `x-tillcast-profiles` of the contract lists the ones a printer can be set to. Only in the answer to a single printer, not in a list.
- `profile_source` (string, optional, nullable) — Where `profile` comes from. `default`: nobody chose, so the default of the paper and the maker applies. `detected`: a Star's own report chose the width. `confirmed`: a calibration code chose it. `explicit`: a request or an edit named it, and every printer made before this field existed. A plain string and not an enum, so that a word added later never breaks a client. Only in the answer to a single printer, not in a list.
- `vendor_source` (string, optional, nullable) — Where `vendor` comes from. `default`: no maker was named, so the printer reads `star` until its first connection names the maker. `detected`: the first connection decided it. `explicit`: the request that made the printer named it, or the printer was made without `paper_width`, or before that field existed: the server never changes an explicit maker. A plain string and not an enum, so that a word added later never breaks a client. Only in the answer to a single printer, not in a list.
- `welcome_print` (boolean, optional, nullable) — Whether the printer prints a welcome receipt on its first connection. An `epson` printer prints none: it reads `false`. Only in the answer to a single printer.

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

- `error` (ErrorObject, required)

### 422 Unprocessable Entity Error

The request is understood but refused. The `code` is one of `profile_unknown`, `profile_not_connectable`, `profile_vendor_mismatch`, `print_options_invalid`, `idempotency_key_reused`.

- `error` (ErrorObject, required)

### 500 Internal Server Error

A problem on Tillcast's side.

- `error` (ErrorObject, required)

### 503 Service Unavailable Error

The service cannot do that now.

- `error` (ErrorObject, required)

## Types

### PrintOptions

What can be set on top of a profile, each field optional. A field left out keeps the profile's own value. The ranges are checked when the printer is made or changed: a value outside its range, or an `encoding` the profile does not take, is `422 print_options_invalid` naming the field.

- `cpl` (long, optional, nullable) — Characters per line, 16 to 96. Left out, the profile's own width, which is the one that fits the paper of the profile.
- `cutting` (boolean, optional, nullable) — Cut the paper at the end of the document. On, unless the profile says otherwise.
- `encoding` (enum, optional, nullable) — The character set of the text sent to the printer. A character the set does not have prints as `?`, and a warning says where.
  - Allowed values: `cp437`, `cp852`, `cp858`, `cp860`, `cp863`, `cp865`, `cp866`, `cp1252`, `multilingual`
- `gamma` (double, optional, nullable) — The gamma of images, 0.1 to 10.
- `gradient` (boolean, optional, nullable) — Dither images with error diffusion, which is smoother, instead of a plain threshold.
- `margin` (long, optional, nullable) — The left margin in characters, 0 to 24.
- `margin_right` (long, optional, nullable) — The right margin in characters, 0 to 24. The renderer reads it for a few kinds of content only (mostly images and QR codes printed upside down); where it does not, a value is accepted and changes nothing.
- `spacing` (boolean, optional, nullable) — Wider line spacing.
- `threshold` (long, optional, nullable) — The brightness at which an image pixel prints black, 1 to 255.
- `upside_down` (boolean, optional, nullable) — Print the document turned by 180 degrees.

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

**Request**

```json
{
  "name": "Reception left",
  "client_reference_id": "kitchen-1",
  "paper_width": "80mm"
}
```

**Response**

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

**SDK Code**

```python
import requests

url = "https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers"

payload = {
    "name": "Reception left",
    "client_reference_id": "kitchen-1",
    "paper_width": "80mm"
}
headers = {
    "Idempotency-Key": "printer-3318-create",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'printer-3318-create',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"Reception left","client_reference_id":"kitchen-1","paper_width":"80mm"}'
};

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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers"

	payload := strings.NewReader("{\n  \"name\": \"Reception left\",\n  \"client_reference_id\": \"kitchen-1\",\n  \"paper_width\": \"80mm\"\n}")

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

	req.Header.Add("Idempotency-Key", "printer-3318-create")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = 'printer-3318-create'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Reception left\",\n  \"client_reference_id\": \"kitchen-1\",\n  \"paper_width\": \"80mm\"\n}"

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/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers")
  .header("Idempotency-Key", "printer-3318-create")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Reception left\",\n  \"client_reference_id\": \"kitchen-1\",\n  \"paper_width\": \"80mm\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers', [
  'body' => '{
  "name": "Reception left",
  "client_reference_id": "kitchen-1",
  "paper_width": "80mm"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => 'printer-3318-create',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "printer-3318-create");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Reception left\",\n  \"client_reference_id\": \"kitchen-1\",\n  \"paper_width\": \"80mm\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Idempotency-Key": "printer-3318-create",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "Reception left",
  "client_reference_id": "kitchen-1",
  "paper_width": "80mm"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

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

**Request**

```json
{
  "name": "Reception left",
  "client_reference_id": "kitchen-1",
  "paper_width": "80mm"
}
```

**Response**

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

**SDK Code**

```python
import requests

url = "https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers"

payload = {
    "name": "Reception left",
    "client_reference_id": "kitchen-1",
    "paper_width": "80mm"
}
headers = {
    "Idempotency-Key": "printer-3318-create",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'printer-3318-create',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"Reception left","client_reference_id":"kitchen-1","paper_width":"80mm"}'
};

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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers"

	payload := strings.NewReader("{\n  \"name\": \"Reception left\",\n  \"client_reference_id\": \"kitchen-1\",\n  \"paper_width\": \"80mm\"\n}")

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

	req.Header.Add("Idempotency-Key", "printer-3318-create")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = 'printer-3318-create'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Reception left\",\n  \"client_reference_id\": \"kitchen-1\",\n  \"paper_width\": \"80mm\"\n}"

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/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers")
  .header("Idempotency-Key", "printer-3318-create")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Reception left\",\n  \"client_reference_id\": \"kitchen-1\",\n  \"paper_width\": \"80mm\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers', [
  'body' => '{
  "name": "Reception left",
  "client_reference_id": "kitchen-1",
  "paper_width": "80mm"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => 'printer-3318-create',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "printer-3318-create");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Reception left\",\n  \"client_reference_id\": \"kitchen-1\",\n  \"paper_width\": \"80mm\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Idempotency-Key": "printer-3318-create",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "Reception left",
  "client_reference_id": "kitchen-1",
  "paper_width": "80mm"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

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