Label, receipt and document templates

A template is a ZPL label, an EPL label, a receipt or a full-page document (HTML) with {{variables}}. Make it once in the dashboard and print it from any app with a template ID and the data:

await jp.print({
  templateId: "tpl_01J9SHIPLABEL",
  data: { order: "10492", customer: { name: "Anne Joseph" } },
});

• Cloud mode (POST /v1/jobs): the cloud fills in the template, and the agent receives ordinary ZPL, EPL or receipt JSON.
• Local mode (browser SDK): every agent of the organization receives the templates in its config and fills them in itself. This works offline too.

Make a template

Dashboard → Templates → New template:

1. Choose the type: ZPL label, EPL label or receipt. The editor starts from a working example.
2. Choose the paper (optional). A job that sets no paper uses the template's paper.
3. Write the template and some sample data (JSON).
   • The preview shows what the printer receives.
   • For receipts, it also shows an image drawn by the agent's own engine.
4. Save. Agents receive the template within seconds. The editor then shows the code to print it.

An organization can have 200 templates, 2 MB in total.

Syntax

Write	Result
{{name}}	The value, escaped for the template type
{{customer.name}}	A nested value
{{{name}}} or {{& name}}	The value as is, not escaped
{{#items}}…{{/items}}	Repeated for each element of a list. An object becomes the context once; other values show the block when they are true, non-empty or non-zero.
{{^items}}…{{/items}}	Shown when the value is missing, false, empty or zero
{{.}}	The current element of a list
{{@index}}, {{#@first}}…{{/@first}}, {{^@last}}…{{/@last}}	Position inside a list (from 0), first and last element
{{! note }}	A comment

A missing value prints nothing. Numbers, true and false print as in JSON; objects and lists print as JSON.

Escaping

Values from your data can never become printer commands:

• ZPL:
  • In a field that starts with ^FH (for example ^FO40,40^A0N,40,40^FH^FD{{name}}^FS), the characters ^, ~, the ^FH indicator and control characters are printed exactly, as hex codes (_5E).
  • In other places, those characters are removed.
  • Put ^FH before ^FD in every field with a value. ZebraDesigner exports already use ^FH\, and the \ indicator is handled too.
• EPL: quotes and backslashes get a backslash, and line breaks are removed.
• Receipts: values are written as JSON string content, so quotes and line breaks are safe. Use {{{rows}}} to insert a list from your data as JSON:

{ "type": "table", "columns": [{ "width": 0.7 }, { "width": 0.3, "align": "right" }], "rows": {{{rows}}} }

or build the rows in the template:

"rows": [{{#items}}["{{name}}", "{{price}}"]{{^@last}},{{/@last}}{{/items}}]

Print from your server

curl https://api.jodaprint.dev/v1/jobs \
  -H "Authorization: Bearer $JODAPRINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deviceId":"dev_…","alias":"label","templateId":"tpl_01J9SHIPLABEL","data":{"order":"10492"}}'

GET /v1/templates lists the templates (scope jobs:read). With the Node SDK:

const { data: templates } = await jp.templates.list();
await jp.jobs.create({ deviceId: "dev_…", templateId: templates[0].id, data: { order: "10492" } });

A job with an unknown template, or data the template cannot render, fails with INVALID_JOB.

Label previews

The dashboard previews ZPL and EPL labels as the commands the printer receives, not as an image. Why is explained in ADR 0040. To see a label drawn, paste the rendered ZPL into a viewer you trust. The rendered output contains your data.

Documents: reports and estimates

A Document (HTML) template is a full page in HTML and CSS, for laser and inkjet printers: reports, estimates, statements.

• The agent prints it through the computer's browser (Chrome or Edge), so the computer needs one of them. Android agents do not print HTML.
• Set the page size and margins in CSS: @page { size: letter; margin: 16mm; }, or size: A4.
• Values are HTML-escaped (<, >, &, quotes), so data never becomes markup. Use {{{html}}} only for HTML you trust.
• Agents from version 1.0.1 receive HTML templates for local mode. Cloud jobs work with any agent version.

Gallery

Dashboard → Templates → Gallery has ready-made designs: 5 receipts, 5 labels, 5 reports and 5 estimates. Use this template opens a copy in the editor, with the printed words (Total, Estimate…) in your language and sample data that shows the variables it expects. Save it, then change it as you like: it is your template.