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

# Your own IDs

> The client_reference_id field of customers, locations, printers and jobs: not unique, optional, searchable.

Customers, locations, printers and jobs each have an `id` that Tillcast makes. Your software has its own ids for the same things: an account number, a venue code, the name of a till, an order number. One field holds yours, on all four kinds: **`client_reference_id`**.

|               |                                                                                                                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Value         | 1 to 128 characters, not blank, no control characters. `null` when absent.                                                                                                          |
| When          | Optional when you create the object. `PATCH` changes a customer, a location or a printer's value, and `null` removes it. A job's is set when the job is queued and does not change. |
| Unique        | **No.** Tillcast does not guard it. Two objects, of one kind or of two, can carry the same value.                                                                                   |
| Personal data | Do not put any in it.                                                                                                                                                               |

## Because it is not unique

* Send an [`Idempotency-Key`](/api/idempotency) with every create. A retry of the same request answers the first object again. Without the key, a create that is sent twice makes two objects, with the same value on both.
* If you need find-or-create, search first, then create when nothing was found.

## Find objects by it

Each list takes `client_reference_id` and answers with every object of your organization that carries that exact value. An unknown value is an empty list, never `404`. The value is compared as it is: no case folding, no trimming, no prefix. The query string is form-decoded, so write a plus sign as `%2B`.

```bash wordWrap
curl "https://api.tillcast.com/v1/customers?client_reference_id=acct-1042" \
  -H "Authorization: Bearer $TILLCAST_API_KEY"
```

The same parameter works on `GET /v1/locations`, `GET /v1/printers` and `GET /v1/jobs`. A search narrows with `customer`, `location` and, for jobs, `printer`. Jobs are found for seven days after they end, newest first. A key limited to one customer finds only that customer's objects.

Do not use one constant value for every job: a search by a value that thousands of objects share is slow when it is narrowed. A search can also answer a short or an empty page with `has_more: true` and a `next_cursor`: follow the cursor until `has_more` is `false`. See [Searches can answer a short page](/api/pagination#searches-can-answer-a-short-page).

## The old names

Earlier names of this field, `external_id` on customers and locations and `reference` on jobs, are refused with `400 parameter_unknown`. Use `client_reference_id`.