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

# Create a customer

POST https://api.tillcast.com/v1/customers
Content-Type: application/json

Adds a customer: the business whose locations and printers you manage. The
customer's id is a short code that is also the first label of the host of
its printers. Needs a key that is not limited to one customer. 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`; 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:** `customers:write`.

Reference: https://docs.tillcast.com/api-reference/customers/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

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

- `name` (string, required) — 1 to 128 characters.
- `client_reference_id` (string, optional, nullable) — The id of this customer 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/customers?client_reference_id=` before you create when you need to find the customer you made earlier.

## Response

### 200

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

- `client_reference_id` (string, required, nullable) — The id of this customer in your own system, or `null`. Not unique: the same value can be on many objects, and `GET /v1/customers?client_reference_id=` lists every customer that carries it.
- `created_at` (string, required)
- `id` (string, required) — `cus_` and the customer's code, which is also the first label of the host of its printers.
- `location_count` (long, required)
- `mode` (string, required) — `live`.
- `name` (string, required)
- `object` (string, required)
- `printer_count` (long, required)
- `state` (string, required) — `active`, or `suspended` (its printers print nothing).

### 201

The customer that was made.

- `client_reference_id` (string, required, nullable) — The id of this customer in your own system, or `null`. Not unique: the same value can be on many objects, and `GET /v1/customers?client_reference_id=` lists every customer that carries it.
- `created_at` (string, required)
- `id` (string, required) — `cus_` and the customer's code, which is also the first label of the host of its printers.
- `location_count` (long, required)
- `mode` (string, required) — `live`.
- `name` (string, required)
- `object` (string, required)
- `printer_count` (long, required)
- `state` (string, required) — `active`, or `suspended` (its printers print nothing).

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

### 422 Unprocessable Entity Error

The request is understood but refused.

- `error` (ErrorObject, required)

### 500 Internal Server Error

A problem on Tillcast's side.

- `error` (ErrorObject, required)

## Types

### 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": "Baltic Hotels Sp. z o.o.",
  "client_reference_id": "acct-1042"
}
```

**Response**

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

**SDK Code**

```python
import requests

url = "https://api.tillcast.com/v1/customers"

payload = {
    "name": "Baltic Hotels Sp. z o.o.",
    "client_reference_id": "acct-1042"
}
headers = {
    "Idempotency-Key": "customer-1042-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/customers';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'customer-1042-create',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"Baltic Hotels Sp. z o.o.","client_reference_id":"acct-1042"}'
};

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/customers"

	payload := strings.NewReader("{\n  \"name\": \"Baltic Hotels Sp. z o.o.\",\n  \"client_reference_id\": \"acct-1042\"\n}")

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

	req.Header.Add("Idempotency-Key", "customer-1042-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/customers")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = 'customer-1042-create'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Baltic Hotels Sp. z o.o.\",\n  \"client_reference_id\": \"acct-1042\"\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/customers")
  .header("Idempotency-Key", "customer-1042-create")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Baltic Hotels Sp. z o.o.\",\n  \"client_reference_id\": \"acct-1042\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.tillcast.com/v1/customers', [
  'body' => '{
  "name": "Baltic Hotels Sp. z o.o.",
  "client_reference_id": "acct-1042"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => 'customer-1042-create',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.tillcast.com/v1/customers");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "customer-1042-create");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Baltic Hotels Sp. z o.o.\",\n  \"client_reference_id\": \"acct-1042\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Idempotency-Key": "customer-1042-create",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "Baltic Hotels Sp. z o.o.",
  "client_reference_id": "acct-1042"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.tillcast.com/v1/customers")! 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": "Baltic Hotels Sp. z o.o.",
  "client_reference_id": "acct-1042"
}
```

**Response**

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

**SDK Code**

```python
import requests

url = "https://api.tillcast.com/v1/customers"

payload = {
    "name": "Baltic Hotels Sp. z o.o.",
    "client_reference_id": "acct-1042"
}
headers = {
    "Idempotency-Key": "customer-1042-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/customers';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'customer-1042-create',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"Baltic Hotels Sp. z o.o.","client_reference_id":"acct-1042"}'
};

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/customers"

	payload := strings.NewReader("{\n  \"name\": \"Baltic Hotels Sp. z o.o.\",\n  \"client_reference_id\": \"acct-1042\"\n}")

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

	req.Header.Add("Idempotency-Key", "customer-1042-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/customers")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = 'customer-1042-create'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Baltic Hotels Sp. z o.o.\",\n  \"client_reference_id\": \"acct-1042\"\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/customers")
  .header("Idempotency-Key", "customer-1042-create")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Baltic Hotels Sp. z o.o.\",\n  \"client_reference_id\": \"acct-1042\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.tillcast.com/v1/customers', [
  'body' => '{
  "name": "Baltic Hotels Sp. z o.o.",
  "client_reference_id": "acct-1042"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => 'customer-1042-create',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.tillcast.com/v1/customers");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "customer-1042-create");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Baltic Hotels Sp. z o.o.\",\n  \"client_reference_id\": \"acct-1042\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Idempotency-Key": "customer-1042-create",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "Baltic Hotels Sp. z o.o.",
  "client_reference_id": "acct-1042"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.tillcast.com/v1/customers")! 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()
```