Building a Template

The Receipt Builder is where you design receipt layouts. A template is an ordered list of commands — each command adds one element to the printed output, such as a line of text, a table row, a barcode, or a separator. Commands are added from a palette, configured in a properties panel, and can be freely reordered. Changes are reflected immediately in the preview.

This page covers every step of the build process: adding commands, setting their properties, using merge tags, building repeating sections, and saving the finished template.

Prerequisites

• A printer must be configured in Settings → Printer before you can use Test Print. The builder itself works without a printer connected.

Screen layout

The builder adapts to the screen size. On desktop (1200 px and above) all three panels — command palette, command list with properties, and preview — are visible side by side. On tablet (600–1200 px) the command list and preview are shown side by side, with a floating + button to open the command palette. On mobile (under 600 px) the Commands and Preview tabs switch between the list and the preview, again with a floating + button.

For the full layout table, see Overview.

Adding a command

On desktop (1200 px and above)

The Add Command panel is always visible on the left. Commands are grouped into four collapsible categories — Content, Layout, Graphics, and Control — with Content expanded by default. Tap any command row to add it to the end of the canvas.

On tablet and mobile

Tap the floating + button at the bottom right. The Add Command sheet slides up, showing the same categories as flat sections. Tap a command to add it and close the sheet automatically.

Available commands

The command list

Every command you add appears as a card in the Commands list. The header shows the command count — for example Commands (5) — and a trash icon to clear all commands at once.

Each card shows:

• A drag handle (top-level commands) — drag up or down to reorder
• An emoji icon representing the command type
• The command name and type label
• A ⋮ menu with Duplicate, Move Up, Move Down, and Delete

Merge Group commands show an expand/collapse arrow. When expanded, their nested commands appear indented below with a vertical accent bar.

When the list is empty, a No commands yet message appears with the prompt Add commands from the palette to build your template.

Selecting and editing a command

Tap a command card to select it. The selected card is highlighted.

• On desktop: the Properties panel (middle column, lower half) shows the command's settings immediately.
• On tablet and mobile: the Edit Properties bottom sheet slides up. Drag the handle to resize it. Tap the × to close without losing changes.

To deselect on desktop, tap the × icon in the Properties panel header.

Command properties

Each command type has its own set of properties. All changes apply in real time and are immediately reflected in the preview.

Text

Table Row

A table row is divided into columns. Each column has its own text, width, alignment, bold, and text size.

1. Tap Add Column to insert a new column. Up to six columns are allowed (minimum column width 2/12).
2. Columns are arranged on a 12-unit grid. The Total width indicator turns green when columns add up to exactly 12, orange when under, and red when over. The app auto-adjusts widths proportionally if the total exceeds 12.
3. Tap a column card to expand it and edit its properties:

Drag the handle on each column card to reorder columns. Tap the red delete icon to remove a column.

Merge Group

A Merge Group iterates over a collection and prints its nested commands once per entry. Use item.* merge tags inside the group to reference fields on each entry.

1. Set the Collection field. Tap the list icon on the right to choose from:
   • Line Items (order.orderForm.lineItems)
   • Discounts (order.orderForm.discounts)
   • Payments (order.orderForm.payments)
2. Under Commands in Group, tap + to add a nested command (Text, Table Row, Divider, Spacer, or Feed Lines).
3. Tap a nested command to edit its properties inline within the group.

The nested commands are also visible in the command list, indented below the Merge Group card.

Feed Lines

One property: Number of Lines (1–10 slider). Advances the paper by the set number of blank lines.

Divider

Spacer

Same as Feed Lines: Number of Lines (1–10).

Barcode

If the data contains a merge tag ({{...}}), format validation is skipped since the actual value is only known at print time.

QR Code

Image

The image command has no editable properties in the visual panel. Configure its source, align, and size via Show JSON (see Viewing and editing JSON).

Cut Paper

Using merge tags

Merge tags insert live order or store data into text at print time. The format is {{path}} — for example, {{order.orderNumber}} or {{store.name}}.

Text fields that support merge tags show a tag icon on the right. Tap it to open the merge tag picker, which groups all available tags by context. Selecting a tag inserts it at the current cursor position.

For a complete list of available tags and collections, see the Overview.

Optional conditions

Any command (except a Merge Group) can be shown conditionally. At the bottom of the properties panel, an Add Condition (Optional) row is shown. Tap it to expand a condition field.

Enter an expression using a merge tag and a comparison operator:

Leave the condition field empty to always print the command. When a condition is set, the row is highlighted in blue to indicate the command is conditional.

Building a Merge Group — worked example

To print each line item on the receipt:

1. From the command palette, add a Merge Group.
2. Tap the group in the command list to open its properties.
3. Tap the list icon next to Collection and select Line Items.
4. Under Commands in Group, tap + → Table Row.
5. In the table row nested inside the group:
   • Set column 1 text to {{item.displayName}} (left aligned, width 8)
   • Set column 2 text to {{item.placedPrice}} (right aligned, width 4)
6. The preview updates to show two sample line items repeating the row.

Saving the template

The canvas must contain at least one command before saving. If you try to save an empty canvas, a warning snackbar appears: Add some commands first before saving.

Save (update existing)

When a template is loaded (the Editing: [name] chip is shown in the top bar), tap ⋮ → Save to overwrite it. A brief loading indicator appears, then a snackbar confirms Template "[name]" saved.

Save As (new template)

Tap ⋮ → Save As... (or Save Template if no template is currently loaded). The Save Template dialog opens:

Tap Save to upload the template to the server. A snackbar confirms Template "[name]" saved. The builder's top bar updates to show the new template name in the editing chip.

Editing template settings

To change an existing template's name, area, stores, or markets without altering its commands, tap ⋮ → Template Settings. The same Save Template dialog opens pre-filled with the current values.

Test printing from the builder

Tap the print icon in the top bar to send the current canvas to the configured printer using sample order data.

• If no commands have been added: Add some commands first to test print
• If no printer is configured: the Printer Not Configured dialog opens with OK and Go to Settings buttons
• While printing: a Printing... card is shown
• On success: Test print successful!
• On failure: the error reason appears in a snackbar

Clearing the canvas

Two ways to clear the canvas:

• Tap ⋮ → Clear All in the top bar
• Tap the trash icon in the Commands list header (only visible when commands exist)

Both show a confirmation dialog: Clear All Commands — Are you sure you want to remove all commands? This cannot be undone. Tap Clear All to confirm.

Viewing and editing JSON

Tap ⋮ → Show JSON to open the template's raw JSON representation.

• In read mode the JSON is selectable text with a Copy button to copy it to the clipboard.
• Tap Edit to switch to edit mode. The JSON becomes editable. Syntax errors are highlighted in red.
• Tap Apply (only available when the JSON is valid) to load the edited JSON back into the builder.
• Tap Revert to discard edits and return to read mode.

Use this view to configure commands with no visual property editor (such as the Image command) or to paste a template JSON from another source.

Related pages

• Overview
• My Templates
• Previewing Receipt Commands
• Receipt Printer Setup