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

# Idempotency

> How the Idempotency-Key header lets you retry the creation of a job, a printer, a location or a customer safely.

A network call can fail after Tillcast has accepted the request. If you simply send it again, you might queue a second job, and a second receipt prints. An idempotency key prevents that.

## Send a key

Add an `Idempotency-Key` header of 1 to 64 visible ASCII characters to any call that creates something: a customer, a location, a printer, a job, or a test print. Use a value that is unique for the operation and the same on every retry of it, for example your own order id plus the kind of document. [Create a print job](/create-a-print-job#retry-safely) shows a job sent twice, with the SDKs and with cURL.

```bash wordWrap
curl https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/jobs \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01" \
  -H "Idempotency-Key: order-4713-bill" \
  -H "Content-Type: application/json" \
  -d '{
    "document": [
      {"type": "text", "text": "Harbour Cafe", "align": "center", "bold": true, "size": 2},
      {"type": "text", "text": "Table 7", "align": "center"},
      {"type": "table", "columns": ["*", {"width": 9, "align": "right"}],
       "rows": [["Flat white", "3.40"], {"type": "rule"}, [{"text": "Total", "bold": true}, {"text": "3.40", "bold": true}]]}
    ],
    "client_reference_id": "order-4713"
  }'
```

## What happens on a retry

| Your retry                  | Answer                                                                                                                                                                                                                                                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Same key, same request      | `200` with the object the first request made, **as it is now**, and the header `Idempotent-Replayed: true`. Nothing new is queued and nothing is rendered again. A job keeps the warnings it had, and has the status it has now: a job that was cancelled since replays as `cancelled`, and one that has printed as `printed`. |
| Same key, different request | `422` with the error code `idempotency_key_reused`.                                                                                                                                                                                                                                                                            |
| No key                      | No protection. Every call creates an object.                                                                                                                                                                                                                                                                                   |

"The same request" means the same operation, the same target and the same body, whatever the order of the keys in the body. A key is remembered for 24 hours, or for as long as its job can still print if that is longer. Keys are separate for each organization.

When you try a call by hand, use a new key each time. The same key with the same body answers with the first job again and prints nothing, which looks like a call that does not work. The same key with a different body is refused. Every example in these docs that sends a different request has a key of its own, so you can run two of them one after the other. If you change the body of an example, change its key too.

**Two requests with the same key at the same moment** make one object. One of them is answered `201` and the others are answered as replays (`200` with `Idempotent-Replayed: true`) and carry the same object, so a client that retries too early, or two servers that handle the same event, still make one job. A concurrent create can also be answered `409 already_exists`, which tells you to retry the request: send the same request again with the same key. See [Errors](/api/errors#what-to-do).

A replay is answered before the state of the printer is looked at. A retry of a job that was accepted is not turned into `429 queue_full` or `409 customer_suspended` because the queue has filled or the customer has been suspended since.

When a replay returns a printer that was created with the key, the printer URL is `null`, because it is shown only once. Rotate the secret to get a new URL. A replayed create of a printer can also answer `503 printer_domain_unavailable` while no printer domain is active, even though the first call succeeded.

A create that is refused writes nothing and leaves its key free for a request that is right.

> **Idempotency is not exactly-once printing**
>
> Idempotency stops duplicate jobs from your retries. Tillcast delivers each job to a Star printer at least once, so after a power cut a Star printer can print the same job twice. Make a repeated print harmless. See [Jobs](/concepts/jobs#delivery-and-duplicates).