SDKs
The SDKs are generated from the API contract. They are pre-1.0: method names can still change before 1.0, so pin the version you use. Both packages are MIT licensed. Anything the SDK does not cover, the HTTP API does.
The old npm package named tillcast is empty. It only points to @tillcast/sdk.
A key prints on real printers, and a client built with only a key calls the live API. Keep the key in an environment variable, never in code, and test with the printer you mean to print on. See Which server the SDK calls.
Send a job
TypeScript
Python
An Idempotency-Key makes a retry safe: the same key answers the first job and prints nothing more. See Create a print job for the whole call, Idempotency and Integrate a point of sale.
The document is an array of blocks. To send ReceiptLine text, use the field receiptline instead of document, with a string.
Which server the SDK calls
Both packages call the live API, https://api.tillcast.com, unless you say otherwise, and a job they create prints on a real printer. Tillcast has no test server: there is no sandbox and no staging API.
To send the calls to another address, for example a stand-in server of your own in automated tests, set the base URL when you build the client: baseUrl in TypeScript and base_url in Python. Write the address without /v1, because the SDK adds the path of every call. With /v1 at the end, every call is 404 route_not_found.
TypeScript
Python
A missing base URL is not an error. baseUrl: undefined in TypeScript and base_url=None in Python both mean the live API, so a client in a test that forgot the setting prints on paper. Read the address as above, so that a missing setting stops the program, and set TILLCAST_BASE_URL=https://api.tillcast.com in production. In unit tests, do not build a client at all: pass your code a fake client of your own. Never call the live API from a test or from an agent unless the owner of the key gave you the key and named the printer.
The README of the packages
The README is the first page of a package on npm and PyPI. From version 0.2.1, the README of both packages leads with creating a print job:
- How to install the package, where to get an API key and how to build the client with
token. - Create a print job: a short receipt as blocks, with a centred title, a table, a rule and a total, and the same receipt as ReceiptLine text in
receiptline. - Retry safely: the idempotency key, which is
idempotency_keyin Python and the property"Idempotency-Key"in TypeScript, and how to see a replay. - Read a job back with
jobs.getand its status, and where the printer id comes from. - A refused document:
422 document_invalid, and how to read theparamof the error.
The rest of the README is what Fern generates for every SDK: the environments, the async client of Python, retries and timeouts. Versions 0.2.0 and earlier have only that generated README, and its one example is customers.create, which is not a job. The code of a package does not change with its README. The page Create a print job has the same call with cURL and more.
Version 0.2.0 and blocks
The job body changed on 2026-10-16: document was an object, {"type": "receiptline", "content": "..."}, and is now an array of blocks. Version 0.1.1 of both packages sends the object, and the API answers 400 parameter_invalid. Version 0.2.0 and later send the array. Update the package and change the call. See the changelog.
- TypeScript.
typepicks the kind of block, and the editor offers the fields of that kind. A field that a kind does not have, a misspelled field and a value of the wrong kind are errors of the compiler. The type of a block isTillcast.Block: give a document that you build in a variable this type, or the compiler readstype: "text"as a string. - Python. The parameters of a request that are objects are dicts (TypedDicts), so write the blocks as plain dicts, as above, and a type checker like pyright checks them. This also holds for
print_options: the model classes of 0.1.1, such asPrintOptions(...), are not accepted by a type checker in a request. The type of a block isBlockParams, for a function that returns a document. The answers are still objects:job.id,job.warnings. - Neither or both.
documentandreceiptlineare both optional in the types, so neither the compiler nor the type checker can see that a call has neither or both. The API answers422 document_invalid.
Notes
- The names of the fields are the names of the API (
client_reference_id,expires_in, and in a barcodemodule_width). In Python the header is the argumentidempotency_key; in TypeScript it is the property"Idempotency-Key". - Errors are exceptions that carry the status and the error body. A
422isTillcast.UnprocessableEntityErrorin TypeScript andUnprocessableEntityErrorin Python, and itsbody.errorhas thecode, theparamand therequest_id. See Errors. The TypeScript error also has a propertyrequestId, but it reads the headerx-request-id, and the API sendsRequest-Id, so it isundefined. Readerr.body.error.request_id(the same value) in both languages, orerr.rawResponse.headers.get("request-id")in TypeScript. An error with no answer behind it, such as a timeout or a refused connection, has no request id. - Both packages retry a request twice, with a growing wait, when Tillcast answers
408,429or a5xx(Python also409). They wait for theRetry-Afterof the answer, up to 60 seconds, so aqueue_full(Retry-After: 30) can hold one call for about a minute. They do not retry a timeout or a dropped connection, the cases where the job may already exist: send the same request again yourself, with the sameIdempotency-Keyand body. SetmaxRetries(TypeScript) ormax_retries(Python) to 0 to turn the waits off. See Retry safely. - Both packages call the live API,
https://api.tillcast.com, by default. SetbaseUrl(TypeScript) orbase_url(Python), without/v1, to call another address. See Which server the SDK calls.