Settings

Rendering settings. A request's settings are deep-merged over the template's, which are merged over the defaults: only the keys you send change, and a section set to null (such as footer: null) is removed. The settings reference explains each key with examples.

paper object

PDF page size. Defaults to A4 portrait.

formatstring

A0 to A6, Letter, Legal, Tabloid or Ledger; A4 by default. Ignored when width and height are set.

Example: A4

widthstringnullable

Custom page width as a CSS length; needs height too.

Example: 100mm

heightstringnullable

Custom page height as a CSS length; needs width too.

Example: 150mm

landscapeboolean

Default value: false

margin object

Page margins as CSS lengths; 20mm top and bottom and 15mm left and right by default. Header and footer are drawn inside the top and bottom margin.

topstring

Example: 20mm

rightstring

Example: 15mm

bottomstring

Example: 20mm

leftstring

Example: 15mm

header objectnullable

Printed across the whole page width inside the top margin; null removes the template's.

htmlstring

Markup of the running header, rendered with the template's language and data. Elements with the classes pageNumber and totalPages show the page numbers.

heightstring

Height of the header box as a CSS length.

paddingstring

CSS padding inside the header box; 0 for designs that run edge to edge.

Default value: 0 10mm

footer objectnullable

Printed across the whole page width inside the bottom margin; null removes the template's.

htmlstring

Markup of the running footer, rendered like the header.

heightstring

Height of the footer box as a CSS length.

paddingstring

CSS padding inside the footer box; 0 for designs that run edge to edge.

Default value: 0 10mm

printBackgroundboolean

Print background colours and images.

Default value: true

scalenumber

Scales the page content, from 0.1 to 2.

Default value: 1

preferCssPageSizeboolean

Let @page rules in the CSS decide the page size instead of paper.

Default value: false

pageRangesstring

Keep only these pages of a PDF; empty keeps all. The page count, the plan's page limit and the units count the pages that are kept.

Default value:

Example: 1-3, 5

waitFor object

When the page counts as loaded, before it is printed or captured.

networkIdle object

auto waits for the load event, the fonts and the requests still running, and for half a second of network idle only on a URL or a document with scripts of its own. true always waits for that half second, false never does.

oneOf

boolean
string

boolean

selectorstringnullable

Wait until an element matching this CSS selector exists and is visible.

Default value: null

timeoutMsinteger

How long to wait for selector, in milliseconds, at most 30,000; then the render fails with render_timeout.

Possible values: >= 0

Default value: 5000

delayMsinteger

An extra pause after everything else, in milliseconds; a value above 10,000 counts as 10,000.

Possible values: >= 0

Default value: 0

tailwindboolean

Compile the Tailwind utility classes the document uses, for templates and plain html alike.

Default value: false

pdf object

PDF output only: what the file says about itself, and its structure for assistive technology.

metadata object

The document properties. The title is what a PDF reader shows in its title bar and a screen reader announces first; PDF/UA-1 requires one.

titlestring

Rendered with the data like the template, so it may use template expressions. Applies to stored templates and to html with an engine; a plain html or url render ignores it, so give such a page a <title> instead.

Example: Rechnung {{ invoice.number }}

authorstring

Rendered with the data like title for stored templates and html with an engine; written as given for plain html, url and Word and PowerPoint templates.

Example: Fennlor Studio GmbH

subjectstring

Rendered like author.

keywordsstring

Rendered like author, as one text; left out of the file when it comes out empty.

taggedboolean

Writes the structure tree (headings, lists, tables, links) a screen reader reads the document by.

Default value: false

outlineboolean

Writes bookmarks from the headings.

Default value: false

ua objectnullable

Makes the file a PDF/UA-1 document (ISO 14289-1): tagged, repaired where the browser's output breaks the standard, and held against veraPDF's machine-checkable rules of PDF/UA-1. true is { "check": "strict" }. The render carries the verdict as accessibility, and the file names itself PDF/UA-1 only when it passed. A passed check does not make a document accessible: alternative texts, reading order and contrast are in the template. Cannot be combined with post.merge_after, and is not available for Word and PowerPoint templates; each answers 400 invalid_request. With an e-invoice the file is a PDF/A-3b and a PDF/UA-1 document at once: both are checked in the file that is delivered, and the render carries both reports. false in a request switches off what the template declares. Asked for by a request whose output is an image, it answers 400 too; declared by an image template it is ignored. No plan limit and no extra unit.

oneOf

boolean
PdfUaOptions

boolean

image object

Image output (png, jpg, webp): the browser window the page is captured in.

widthinteger

Window width in CSS pixels; 1200 by default.

Example: 1200

heightinteger

Window height in CSS pixels; 630 by default.

Example: 630

deviceScaleFactornumber

Pixel density: 2 makes a 1200 × 630 window a 2400 × 1260 image.

Default value: 2

formatstring

Output of an image template when the request names no output. jpg is accepted as well.

Possible values: [png, jpeg, webp]

qualityinteger

JPEG and WebP quality; 90 by default.

Possible values: >= 1 and <= 100

fullPageboolean

Capture the whole height of the page instead of the window.

Default value: false

transparentboolean

Transparent background (PNG).

Default value: false

clipSelectorstringnullable

CSS selector of one element to capture instead of the window; the first match counts. When none appears within 30 seconds, the render fails with render_timeout.

Default value: null

office object

Word and PowerPoint templates. Page setup, margins, headers and footers come from the document; the Chromium settings above do not apply.

outputstring

Output when the request names none; the template's own format without it.

Possible values: [docx, pptx, pdf]

localestring

BCP 47 tag that formats dates and numbers, picks the translation dictionary and sets <html lang>; en-GB by default.

Example: de-DE

timezonestring

IANA time zone for dates; Europe/Berlin by default.

Example: Europe/Berlin

currencystring

ISO 4217 code the money helper uses when none is given; EUR by default.

Example: EUR

einvoice objectnullable

Makes the template an invoice template: every PDF rendered from it is a ZUGFeRD / Factur-X e-invoice built from the _invoice block of the data, as if the request said post.einvoice. A request's settings.einvoice and post.einvoice merge over it field by field; post.einvoice: false switches it off for one request. Image output of the same template is not affected. false in a request switches off what the template declares.

oneOf

EinvoiceOptions
boolean

What kind of e-invoice a render makes. Every field has a default, so {} asks for a Factur-X invoice in the EN 16931 profile.

profilestring

en16931 carries every field of the European standard; basic is the smallest profile that is an invoice on its own. Any other profile answers 422 einvoice_profile_unsupported.

Possible values: [basic, en16931]

Default value: en16931

flavourstring

ZUGFeRD and Factur-X are one specification under two names, and the file is the same. The choice decides the name and release the render reports (Factur-X 1.09 or ZUGFeRD 2.5).

Possible values: [factur-x, zugferd]

Default value: factur-x

xmlstring

both stores the XML as a file of its own beside the PDF, kept and deleted with it; the render links it as einvoice.xml_url.

Possible values: [embedded, both]

Default value: embedded

display_checkstring

What happens when the PDF does not show a value of the XML (the invoice number, the totals): warn reports it in einvoice.display.missing, strict fails the render with 422 einvoice_display_mismatch.

Possible values: [warn, strict]

Default value: warn

design object

The visual editor's layers of an image template, stored with a version. Authoring data only: renders use the version's HTML and CSS, which the editor writes from it, and a render request's design is ignored. Kept as it is when you copy a version; at most 256 kB. See the visual editor guide.

property name*any

Settings
{
  "paper": {
    "format": "A4",
    "width": "100mm",
    "height": "150mm",
    "landscape": false
  },
  "margin": {
    "top": "20mm",
    "right": "15mm",
    "bottom": "20mm",
    "left": "15mm"
  },
  "header": {
    "html": "string",
    "height": "string",
    "padding": "0 10mm"
  },
  "footer": {
    "html": "string",
    "height": "string",
    "padding": "0 10mm"
  },
  "printBackground": true,
  "scale": 1,
  "preferCssPageSize": false,
  "pageRanges": "1-3, 5",
  "waitFor": {
    "networkIdle": true,
    "selector": null,
    "timeoutMs": 5000,
    "delayMs": 0
  },
  "tailwind": false,
  "pdf": {
    "metadata": {
      "title": "Rechnung {{ invoice.number }}",
      "author": "Fennlor Studio GmbH",
      "subject": "string",
      "keywords": "string"
    },
    "tagged": false,
    "outline": false,
    "ua": true
  },
  "image": {
    "width": 1200,
    "height": 630,
    "deviceScaleFactor": 2,
    "format": "png",
    "quality": 0,
    "fullPage": false,
    "transparent": false,
    "clipSelector": null
  },
  "office": {
    "output": "docx"
  },
  "locale": "de-DE",
  "timezone": "Europe/Berlin",
  "currency": "EUR",
  "einvoice": {
    "profile": "en16931",
    "flavour": "factur-x",
    "xml": "embedded",
    "display_check": "warn"
  },
  "design": {}
}