PDF templates

Design branded PDF invoice layouts in the Beliq dashboard, then render them from the API with pdfTemplateId. Logo, colours, fonts, a repeating footer and page numbers, and page margins.

A PDF template is your own branded invoice layout: logo, colours, fonts, a footer, page numbers, margins. You design it visually in the dashboard, save it, and then render invoices with it from the API by passing its short id.

Templates are optional. By default Beliq can render the built-in template: "standard" layout, which is also what the free generator uses. A custom template replaces that with your own design.

Where a template applies

A template controls the visible page of a PDF, and only the visible page:

• For the XML-only standards (xrechnung, peppol-bis, fatturapa, facturae, eslog), a PDF request produces a visualization PDF: a human-readable rendering with no embedded XML. It needs a template.
• For ZUGFeRD / Factur-X, the PDF is a hybrid PDF/A-3 with the legal XML embedded inside it. A template styles the visible page; without one, that page is blank.

Starter designs

When you create a template you start from one of the built-in designs (or a blank page). Each is a complete, editable layout, so you can pick the closest one and change colours, fonts and fields rather than build from scratch. Click any design to open its sample PDF, rendered from placeholder invoice data.

Classic RedNeatTeal PanelSlate RoseEditorialDark & GoldElegant TaupeWarm AmberLavenderSteel BlueMinimal WordmarkAngled Slate

Create a template

In the dashboard, open PDF templates and choose New template. Pick a starter design (or Blank), give it a name, adjust the layout, and save. Everything is scoped to your organization.

To start from an existing design instead of a blank layout, use Clone on that template’s row in the list. It immediately saves an editable copy named <name> (copy); open the copy with Edit to change it. The original is untouched, and the copy is a fully independent template with its own short id, so referencing it from the API means passing the copy’s short id.

The editor is a visual designer: drag fields onto the page, resize them, set fonts and colours. Invoice data goes in through placeholders inside read-only text fields; the line-item table, the payment QR and your logo are placed as their own fields.

Fill in invoice data with placeholders

Write a placeholder in curly braces anywhere in a read-only text field and Beliq replaces it with the value from the real invoice when the PDF is generated. One field can mix several placeholders with your own text, so a whole address block or a labelled VAT line is a single field to position:

{sellerName}
{sellerStreet}
{sellerPostalCode} {sellerCity}
VAT: {sellerVatId}

Clicking a value in the editor’s field palette inserts such a field ready-made; edit its content to combine values. The palette carries the complete list of placeholder names, grouped by topic (document, seller, buyer, lines, VAT, totals, payment).

The field must be read-only. That is what marks its content as fixed text to fill in rather than a data slot; palette-inserted fields already are. Saving checks every placeholder, so a typo like {sellerCityy} errors at save instead of printing braces on an invoice.

An empty value renders as nothing. For a postal address that also skips empty lines (no gap when there is no second street line), use a block placeholder:

Block fields drop both the value and any associated label or separator when the underlying data is absent. So a footer field with {sellerImprint} never prints a stray · when the phone number is missing, and {paymentAccount} leaves no “IBAN” label if the seller has no IBAN configured.

More broadly, the visible page may contain presentational elements — a logo, a notes field, a “Scan to pay” QR — that have no equivalent in the embedded XML. That is by design: the rule is non-contradiction, not containment. The PDF face must not show different amounts, parties or dates than the XML; it may show extras that the XML does not carry.

Beyond invoice data, pdfme provides {currentPage} and {totalPages} (see page numbers below) and {date} / {dateTime}, the date the PDF is generated.

Line items, VAT breakdown, payment QR, logo

Three things are fields of their own rather than placeholders: items (the auto-paginating table of invoice lines), vatBreakdown (the per-rate VAT table) and paymentQr (a scannable SEPA payment QR code, covered in QR codes below). Insert them from the palette; they bind by field name.

Add a logo by placing an Image field and uploading PNG or JPEG artwork into it.

Fonts

Text fields offer a fixed set of fonts, embedded into the generated PDF:

If your invoices carry names or addresses with less common characters, DejaVu Sans is the safest choice.

QR codes

The designer has two barcode field types you can drag onto the page: a QR code (2D, field type qrcode) and a Code 128 linear barcode (code128). Both render as sharp vector graphics, so they stay crisp at any zoom or print size. There are two ways to use a QR code, depending on whether its content is fixed or comes from each invoice.

A fixed QR code

Place a QR code field and type its content straight into the designer: a link to your customer portal, your website, a support address, a plain text note, anything. Beliq prints that exact content on every invoice, untouched. Use this for anything that is the same across all your invoices.

Style it from the field’s panel with barColor for the modules (default black) and backgroundColor for the quiet zone (default white). Keep strong contrast and a bit of white margin around the code so scanners read it reliably.

A scannable bank-transfer QR (SEPA)

The paymentQr field is the working payment use case. Instead of fixed content, Beliq fills it per invoice with a GiroCode, the EPC069-12 SEPA credit-transfer code that essentially every European banking app recognizes. Your customer scans it and their banking app opens a transfer already pre-filled with your IBAN, your name, the exact amount due, and the invoice number as the reference. No manual typing, no transposed account digits.

Insert it from the field palette’s Payment group, or start from a template that already places it: the Neat and Teal panel starters both include a “Scan to pay” QR. It binds by the field name paymentQr, so keep that name.

Beliq only fills the code when it can produce a genuinely scannable transfer. All of these must hold, or the field is left as-is:

When Beliq fills the code it encodes the seller name, IBAN, the BIC if you supplied one, the gross total, and Invoice <number> as the remittance reference. When any requirement is not met (a USD invoice, or one with no IBAN, for example) Beliq leaves the field untouched: it shows whatever static content you placed in it, or nothing. So a paymentQr field is safe to leave in a template you also use for non-EUR invoices; it simply stays blank on those.

Content and Page

The editor has two tabs that switch what you are editing.

Content is the main invoice body: the title, parties, the line-item table, totals, payment block. This is the part that flows onto more pages when a long invoice does not fit on one page.

Page is everything that repeats on every page, no matter how many pages the invoice grows to: page margins, page numbers, a footer, a logo, a watermark. The line-item table paginates through the Content layer, but a footer or page number only appears on every page if it lives on the Page layer.

Elements on the Page layer can sit anywhere, including in the margin band, so a footer at the very bottom edge or a logo in a corner both work.

Page numbers

Add a text field on the Page tab with the content Page {currentPage} of {totalPages} and keep it read-only (the same placeholder syntax as invoice data). Beliq fills in the numbers per page at generation time (Page 1 of 3, Page 2 of 3, and so on). On a single-page invoice it renders Page 1 of 1.

Page margins

Margins (top, right, bottom, left, in millimetres) are a page-level setting, so they live on the Page tab. They control where the Content body sits; the Page layer itself can still reach into the margin band, which is how a footer sits below the body.

Preview and save

Preview renders the current template against sample data so you can check the layout before saving. Save stores the template on your organization.

Use a template from the API

Each saved template shows a short ref (a k3d-9mp-style code) next to its name in the list — click it to copy. Pass that ref as pdfTemplateId on POST /v1/generate:

{
  "standard": "zugferd",
  "profile": "en16931",
  "output": "pdf",
  "pdfTemplateId": "k3d-9mp",
  "invoice": { }
}

pdfTemplateId takes precedence over template. Because templates are org-scoped, the request must be authenticated with your API key. If the ref is wrong or the request is unauthenticated you get a PDF template error.

Notes and limits

• Page size is A4 (210 x 297 mm). The built-in layout and the starter footer / page-number fields are positioned for A4.