Document templates
Overview
Document templates govern how a PDF looks — quote, invoice, delivery note and everything else. A template applies per document type, brand and language.
Two ways of editing are available: Visual for the normal case and Twig for templates that demand more than an interface can express. Both edit the same template; the mode is shown in the list.
Everything here is changeable without a release. A layout request is not a development job.
Core tasks
Create a template. New template requires document type, brand and language. The list can be filtered by document type and brand.
Use the fallback principle. As with mail templates: a template without a brand is the global edition for every brand; a template with a brand beats it there. Maintain one global edition and create brand editions only where things genuinely differ.
Activate. Only active templates are used. That lets you prepare a new edition and switch over only once it has been checked.
Fields in detail
| Field | Required | Values / format | What it does |
|---|---|---|---|
Document type docType | yes | invoice, quote, order, delivery note … | Which document the template applies to. |
Brand brandId | no | one of your brands | For which brand. A brand-specific template beats the general one. |
Language locale | no | language code, max. 10 characters | For which language. That way an English customer gets an English layout, not merely translated field content. |
Customer group customerGroupId | no | an existing customer group | Which customer group the template applies to. Empty = all of them. Selection always takes the more specific template before falling back to the brand's. |
Sales channel salesChannelId | no | an existing sales channel | Which sales channel the template applies to — that way a marketplace document can look different from a direct one. Empty = all of them. |
Name name | yes | text, max. 120 characters | What the template is called in the selection. |
Editing mode editorMode | no | visual or template language | How the template is maintained. The visual route suffices almost always; the template language is for cases blocks cannot express — it demands care, because an error makes the document unproducible. |
Blocks blocks | with "visual" | list of blocks | Header, address field, items, totals, footer — and the Swiss QR bill payment part (qrBill): receipt and payment part on a separate last page, only on invoices in CHF or EUR and only when the brand has switched it on (see Brands). |
Body body | with "template language" | text | The template as source. |
Background PDF backgroundPdfFileId | no | PDF file | Stationery printed over. The usual route when your paper is already designed. |
Logos logos | no | image files | The template's logos. |
Default isDefault | no | yes/no | Which template is used when none is chosen on the document. |
Active active | no | yes/no | Off means no longer selectable. Documents already produced keep their appearance — a document is a product, not a view of the template. |
Text blocks for header and footer text
Below the template list lies the one catalogue of reusable document texts — for quote, order, invoice and delivery note. Do not confuse it with the cover texts of the dispatch email: those appear in the email, these on the document itself. The quote text blocks of earlier versions have been moved here.
| Field | Required | Values / format | What it does |
|---|---|---|---|
Name name | yes | text, max. 150 characters | How the block is named in the selection on the document. |
Kind category | yes | header text or footer text | Whether the block goes above the line items or below the total. |
Document type documentType | no | quote, order, invoice, delivery note — empty for all | For which document type the block is offered. A block without document type is available to every type. |
Content content | no | formatted text | The text itself. Active content (scripts) is removed on save. |
Brand brandId | no | one of your brands | For which brand. Empty = for all brands. |
Default isDefault | no | yes/no | Inserted automatically in new documents of this type. There is at most one default per kind, document type and brand; a new one replaces the old. The lookup goes from specific to general: document type and brand, then document type, then all document types with brand, then all. |
Active active | no | yes/no | Off means: no longer selectable on the document. Texts already inserted stay on the document. |
Order sortOrder | no | number | Order in the selection. |
Settings & permissions
- Permission
platform.settings.manage. Without it the page is unreachable. - No PDF engine, no document. PDF generation is a separate part of the installation. If it is
missing, no document is produced — that is not a template question and belongs with your administrator.
- Issued documents do not change retroactively. A template change affects future generations.
- Numbers come from elsewhere. The document number comes from the
number schemes, not from the template.
FAQ & troubleshooting
The document is not generated. First check whether an active template exists for the combination of document type, brand and language. If it persists, the installation's PDF generation is the cause.
The document carries the wrong logo. The logo comes from the brand, not from the template.
A change does not show on an old document. By design: a generated document is a document, not a window onto the current template.
Visual editing is not enough. Then the Twig mode is the route. It does, however, require knowledge of the template language — otherwise the mistake surfaces at the customer's end.