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

# Pagination

> How lists in the Tillcast API are paged with limit, starting_after and ending_before.

Every list endpoint pages the same way, as Stripe does.

| Parameter        | Meaning                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `limit`          | Page size, 1 to 100. The default is 10.                                                               |
| `starting_after` | The id of the last object on the page you hold. Returns the next page.                                |
| `ending_before`  | The id of the first object on the page you hold. Returns the previous page. Do not send both cursors. |

A list answers with `object`, `data` and `has_more`.

```json wordWrap
{
  "object": "list",
  "data": [
    {
      "id": "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
      "object": "printer",
      "name": "Reception left",
      "vendor": "star",
      "status": "online"
    }
  ],
  "has_more": true
}
```

The objects in `data` are shown cut down here. A real list holds the full objects.

The order is fixed: customers by code, locations and printers by customer, location and creation, and jobs newest first.

## Walk a list

#### Ask for the first page

```bash wordWrap
curl "https://api.tillcast.com/v1/printers?limit=50" \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01"
```

#### Ask for the next page

While `has_more` is `true`, pass the id of the last object as `starting_after`.

```bash wordWrap
curl "https://api.tillcast.com/v1/printers?limit=50&starting_after=prn_01M44X7TQ0A9R2H5J8K1M4N7P0" \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01"
```

An id that is not an object of that list, one that belongs to another organization, or a made-up one gives `400` with `invalid_cursor`.

## Searches can answer a short page

A search by `client_reference_id` reads only so many rows in one request. It may answer fewer than `limit` objects, even none, with `has_more` set to `true` and a `next_cursor`. This is for a value that very many objects carry, most of all when the search is narrowed with `customer`, `location` or `printer`.

```json wordWrap
{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "cus_c3x9k2m3"
}
```

**An empty page with `has_more: true` is not the end, and it is not "nothing found".** Send the `next_cursor` as `starting_after` (or as `ending_before`, if you page backwards) and ask again, until `has_more` is `false`. Only then does every object that carries the value come exactly once.

```bash wordWrap
curl "https://api.tillcast.com/v1/customers?client_reference_id=acct-1042&starting_after=cus_c3x9k2m3" \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01"
```

* `next_cursor` is an id of the kind of the list. It is not always the id of an object in `data`, and it is accepted as a cursor like any other id of the kind.
* A page that fills has no `next_cursor`: continue from its last object, as above.
* `has_more` can be `true` when nothing follows. The request that ends the walk then answers an empty page.
* A list that is not a search has no `next_cursor`.
* Version 0.2.1 of the SDKs does not declare `next_cursor` in its types, but both return it on the page they give you: `(page as { next_cursor?: string }).next_cursor` in TypeScript, and `page.next_cursor` in Python (it is also in `page.model_extra`). Read it there until the types have it.

Prefer a list by location, `GET /v1/locations/{location}/printers`, or by customer, `GET /v1/customers/{customer}/printers`, to a list of all the printers of the organization. The organization-wide list, `GET /v1/printers`, is slower and has no status filter. The lists by location and by customer take `status=` to filter by the printer's status.