Skip to navigation

The job body is an array of blocks

This is a breaking change of the body of a job, made under the same API version, 2026-10-01. There is no alias and no migration period: the earlier body is refused. SDK 0.2.0 follows and sends the new body.

  • document is an array of blocks. Each block is one visible unit and says its type: text, row, table, rule, cut, feed, barcode, qr or image. Tillcast renders the document for the printer’s profile, as before. The text of a block prints as it is written, so there is nothing to escape. See Receipt documents.
  • receiptline is the field for ReceiptLine text. It is for documents written for other ReceiptLine tools. The escape rule applies to this text only. To keep a document as it is, send the text that was document.content as receiptline.
  • Exactly one of the two. A job with both document and receiptline, or with neither, is 422 document_invalid. A job with no document at all was 400 parameter_missing before.
  • The earlier body is gone. {"document": {"type": "receiptline", "content": "..."}} is 400 parameter_invalid, and the message says where the text goes now. Where an error said document.content in param, it now says receiptline.
  • A new error for blocks. A block that cannot be printed as it is said is 422 document_invalid, and param is the path of the first problem, such as document[3].rows[1][0].size.
  • SDKs. Version 0.1.1 of @tillcast/sdk and tillcast sends the earlier object, and the API refuses it. Version 0.2.0 sends the array. In Python the blocks, and also print_options, are written as plain dicts, and a type checker no longer accepts the model classes of 0.1.1 in a request. See SDKs.
  • Pages. The examples of the Quickstart, Jobs, Idempotency, Integrate a point of sale and SDKs send blocks, and so does the AGENTS.md snippet of Build with an agent.

One field for your own IDs, and a full test page

  • client_reference_id. Customers, locations, printers and jobs carry the id they have in your own system in one field with one name. It is not unique, and every list can search by it. It replaces external_id on customers and locations and reference on jobs, which are now refused with 400 parameter_unknown. See Your own IDs.
  • The external_id_taken error is gone. A value is never refused for being used already.
  • Old request shape removed. A job body with media_type and payload_base64 is refused like any unknown field. A job carries a document.
  • Full test page. Test print in the dashboard queues a long page, about 80 cm of paper, with every barcode type, QR code and image. With the API, call the test print with ?page=full. See First connection.
  • New page. Integrate a point of sale says what the code of a till or an order system needs.
  • SDKs. The TypeScript package @tillcast/sdk and the Python package tillcast are published as pre-1.0 versions (0.1.1). See SDKs. The npm package tillcast without a scope is empty and points to @tillcast/sdk.