Skip to main content

How PDF templates work

A template is a page layout with fill-in-the-blank placeholders. Understanding what those placeholders can and can't do — and which template a given document picks up — explains most of the surprises people hit in the builder.

What the template language can and cannot do​

The language is deliberately simple. It can do exactly three things:

  • Print a value — a number, a name, a date.
  • Repeat a block once per line — the items table.
  • Show or hide a block based on a yes/no switch.

That's the whole list. There is no arithmetic, no comparing two values, no "if this equals that", and no sorting, filtering, counting or looking anything up. So none of these can be written in a template:

  • "Only show the discount when it's more than zero" — use the matching yes/no switch instead.
  • "Price times quantity" — use a total that's already supplied to you.
  • "Sort items by SKU" — row order comes from the record, and has to change there.

If you need a calculated number, look for one that already exists in the Variables panel. If you need something on only some documents, use a yes/no switch or a destination conditional.

Two and three braces

Most placeholders use two braces and insert plain text. A few use three braces because they insert ready-made markup rather than text — a formatted address block, a logo, an uploaded image. Use whichever form the Variables panel gives you; swapping one for the other prints the markup as visible characters or strips the formatting.

Showing and hiding a block​

A yes/no entry in the Variables panel can wrap part of your template so it prints only in certain cases — a note that appears only on pickup orders, a discount row that appears only when there is a discount.

Clicking one of these entries inserts a matching opening and closing pair; you place your content between them. Each switch also has an inverted form that prints its contents in every other case, so you can pair the two for "this when it applies, that otherwise".

Every opening block must have its closing partner. A template missing one is rejected when you save, with the offending block named in the error.

Blank values, and the labels stranded beside them​

Any value that's missing on a particular record — no store message, no customer reference, no second address line, no custom field value, no note — is replaced with nothing at all. There's no error and no placeholder text.

The words you typed beside it still print, though. That's how you end up with Notes: followed by white space, or a heading over an empty box. The fix is always the same: put the label or heading inside the show/hide block for the value it describes, so the whole section disappears together.

Two details worth knowing:

  • Zero is a real value and prints as 0. A genuinely missing amount prints as nothing at all. They look different on the page.
  • A record with no address at all produces an empty result for every address field, so the block prints as blank space. Wrap the whole address area, heading included.

Which template a document actually uses​

Every document type has one global template that all stores use. If the store on the record — the order, quote, purchase order, credit or pick list — has its own version of that type, that version wins and the global one is ignored for that store. A record with no store always uses the global.

This works the same way for all seven document types. A pick list is the one worth spelling out, because a sheet can cover many orders: it uses a store's version only when every order on the sheet belongs to that one store. A multi-store batch has no single store to resolve, so it prints the global template — the same condition that leaves the store name and logo blank on the sheet itself.

So when a store's documents don't show a change you made, you almost certainly edited the global while that store has its own copy — or the reverse. Check the Stores dialog first. The editor toolbar also shows a Store override chip naming the store whenever you're editing a copy rather than the global.

When a document type has no template​

Every document type needs a template before it can be printed. If neither a global template nor a store copy exists, the print or download fails outright and nothing is produced.

Packing slips, the sales order invoice and pick lists say so plainly and point you at Settings → PDF Templates. Quotes, sales credits and vendor credits fail with a generic error instead — so if Download PDF on one of those errors, check that the matching template exists before looking anywhere else.

The fix is to open that type's template and use Reset to default, which repopulates it from the shipped design. New accounts are seeded with a default for all seven types, so this normally only happens when a template has been deleted.

New vs Legacy (Jasper) packing slips​

Everywhere a packing slip can be printed, two options sit next to each other: New and Legacy (Jasper).

  • New builds the document from the Packing Slip template you edit in Settings → PDF Templates. Every change you make there — layout, logo, highlights, per-store version — shows up on the printed slip.
  • Legacy (Jasper) runs the older fixed report and ignores your template completely. Nothing you edit affects it. It exists only as a fallback while the old renderer is retired.

If a warehouse reports that their slips don't reflect your changes, check which option they're using. The print history on a fulfillment order labels each print New or Legacy, so you can tell which one produced any given copy.

Next steps​

Last verified: