RenderRequest
One render. Send exactly one source: template, html or url (400 invalid_request otherwise).
The template, by slug or id (tpl_…; the UUID works too). Omit when using html or url.
Possible values: <= 200 characters
invoice-depublished (default), the name of a release channel such as staging (Starter plan and above), latest (the newest version, usually the draft the editor works on; test keys only) or a version number. Channels, published included, are cached for up to a minute; a channel with a canary sends its share of renders to the canary version, chosen by canary_key, else by the Idempotency-Key so a retry lands on the same version, else at random. A draft renders as it is at that moment.
publishedAd-hoc HTML, at most 5 MB. With an engine it is rendered as a template over data, with the brand kit and the shared partials; without one it is printed as given.
A public https page to print, up to 2,048 characters. It is loaded like a browser would, without your cookies or headers. Private, internal and metadata addresses are refused: with 400 invalid_request where the address shows it, with 422 navigation_failed where a name resolves to one. Plain http, an HTTP error status or a page that does not load within 30 seconds fail with 422 navigation_failed. URL renders are never deduplicated.
The template language of html; left out or null, the HTML is not templated.
Possible values: [jinja2, liquid, handlebars]
data object
The data the template renders with; {} when left out. Plain html and url renders read only its _invoice block, for an e-invoice. It is checked against the template's schema only with validate_data.
The data the template renders with; {} when left out. Plain html and url renders read only its _invoice block, for an e-invoice. It is checked against the template's schema only with validate_data.
Left out, the template decides: pdf for a template of kind pdf, settings.image.format (the request's, then the template's; png without one) for kind image, settings.office.output (else the template's own format) for kinds docx and pptx. Ad-hoc html and url render pdf. On the Free plan, test renders of docx and pptx templates may only request pdf (403 test_output_unavailable).
Possible values: [pdf, png, jpg, webp, docx, pptx]
settings object
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.
A0 to A6, Letter, Legal, Tabloid or Ledger; A4 by default. Ignored when width and height are set.
A4Custom page width as a CSS length; needs height too.
100mmCustom page height as a CSS length; needs width too.
150mmfalsemargin 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.
20mm15mm20mm15mmheader objectnullable
Printed across the whole page width inside the top margin; null removes the template's.
Markup of the running header, rendered with the template's language and data. Elements with the classes pageNumber and totalPages show the page numbers.
Height of the header box as a CSS length.
CSS padding inside the header box; 0 for designs that run edge to edge.
0 10mmfooter objectnullable
Printed across the whole page width inside the bottom margin; null removes the template's.
Markup of the running footer, rendered like the header.
Height of the footer box as a CSS length.
CSS padding inside the footer box; 0 for designs that run edge to edge.
0 10mmPrint background colours and images.
trueScales the page content, from 0.1 to 2.
1Let @page rules in the CSS decide the page size instead of paper.
falseKeep 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.
1-3, 5waitFor 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.
- boolean
- string
Wait until an element matching this CSS selector exists and is visible.
nullHow long to wait for selector, in milliseconds, at most 30,000; then the render fails with render_timeout.
Possible values: >= 0
5000An extra pause after everything else, in milliseconds; a value above 10,000 counts as 10,000.
Possible values: >= 0
0Compile the Tailwind utility classes the document uses, for templates and plain html alike.
falsepdf 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.
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.
Rechnung {{ invoice.number }}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.
Fennlor Studio GmbHRendered like author.
Rendered like author, as one text; left out of the file when it comes out empty.
Writes the structure tree (headings, lists, tables, links) a screen reader reads the document by.
falseWrites bookmarks from the headings.
falseua 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.
- boolean
- PdfUaOptions
image object
Image output (png, jpg, webp): the browser window the page is captured in.
Window width in CSS pixels; 1200 by default.
1200Window height in CSS pixels; 630 by default.
630Pixel density: 2 makes a 1200 × 630 window a 2400 × 1260 image.
2Output of an image template when the request names no output. jpg is accepted as well.
Possible values: [png, jpeg, webp]
JPEG and WebP quality; 90 by default.
Possible values: >= 1 and <= 100
Capture the whole height of the page instead of the window.
falseTransparent background (PNG).
falseCSS 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.
nulloffice object
Word and PowerPoint templates. Page setup, margins, headers and footers come from the document; the Chromium settings above do not apply.
Output when the request names none; the template's own format without it.
Possible values: [docx, pptx, pdf]
BCP 47 tag that formats dates and numbers, picks the translation dictionary and sets <html lang>; en-GB by default.
de-DEIANA time zone for dates; Europe/Berlin by default.
Europe/BerlinISO 4217 code the money helper uses when none is given; EUR by default.
EUReinvoice 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.
- 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.
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]
en16931ZUGFeRD 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]
factur-xboth 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]
embeddedWhat 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]
warndesign 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.
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.
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.
Name of the output file, up to 200 characters, as the download URL and Content-Disposition show it. It is taken as written: template expressions are not evaluated, so build the name in your code. Characters other than letters, digits, ., -, _, (, ) and spaces become _, the name is cut to 150 characters, and the output's extension is added when missing. document.<extension> when left out.
invoice-2026-0042.pdfSeconds until the output expires, at least 1. It shortens the retention the plan and the workspace set and cannot lengthen it: a longer value is cut to that retention. null uses the retention. A test render is kept a day at most. On plans without a retention limit (Business and above) an output without expires_in and without a workspace retention never expires.
Possible values: >= 1
The workspace's setting when left out, signed unless it says public. signed: download_url carries a signature and works for seven days at most; read the render again for a new link. public: a plain CDN URL that anyone who has it can open until the output expires.
Possible values: [public, signed]
sync answers with the finished render, or 202 after 60 seconds while it continues in the background; async answers 202 at once.
Possible values: [sync, async]
syncOverrides the locale of a template or of html with an engine: formats dates and numbers and selects the translation dictionary. Plain html and url renders take settings.locale instead.
Possible values: <= 20 characters
Receives render.completed or render.failed for this render, synchronous or not. An https URL on a public host, up to 2,048 characters; unsigned unless webhook_secret is set.
Signs the deliveries to webhook_url (same scheme as an endpoint secret). Write-only, never returned; without it those deliveries stay unsigned.
Possible values: >= 16 characters and <= 200 characters
meta object
Your own data (an order id, say), returned unchanged with the render and in its webhook events.
Your own data (an order id, say), returned unchanged with the render and in its webhook events.
Where the render runs; the workspace's region when left out. Leave it out: every workspace is in eu today.
Possible values: [eu, us, apac]
Answer a request identical to one of the last 24 hours in the workspace (the same template version or HTML, data, settings, locale, output and access, and the same brand kit and shared partials) from the earlier render at zero units. The answer is the earlier render, with its id, file and expiry, deduplicated: true and this request's meta. Live keys only; never for url renders, renders with post (an e-invoice included) or with a storage.key. false always renders.
trueDecides the canary split of a channel: renders with the same value land on the same version, so one customer's documents look alike. Use an opaque id; it is not stored. Without it the Idempotency-Key decides, which keeps a retry on its version but splits separate renders independently.
Possible values: non-empty and <= 200 characters
customer-4711Checks data against the template's stored data schema before anything is rendered or counted; a mismatch answers 422 data_validation_error listing every error. Needs a template with a stored schema (400 otherwise). In a batch, nothing is queued unless every item that asks for it fits.
falsepost objectnullable
Post-processing of a PDF render, applied in the order merge, watermark, password (0.5 units
per step on live keys; Starter plan and above, 403 forbidden with
feature: post_processing below), and the e-invoice, which is a step of its own (one unit;
live renders from the Starter plan on). Test renders make a limited number of e-invoices a
day, each with the test mark: 20 on Free, 100 on Starter, 500 on Pro and 2,000 on
Business; Enterprise does not count them. Post-processing on an image output answers 400.
An unknown step is refused, never skipped.
einvoice object
Makes the PDF a ZUGFeRD / Factur-X e-invoice: a PDF/A-3b that carries the invoice as
XML, built from the _invoice block of data and validated before the file is
delivered. A block that is missing or breaks a rule of EN 16931 answers 422
einvoice_data_invalid before anything is rendered; a file that fails validation is
never delivered, and never replaced by a plain PDF. Not together with password (PDF/A
forbids encryption), and never served from the dedup cache. With settings.pdf.ua the
same file is held to PDF/UA-1 as well, and the render carries accessibility beside
einvoice. false switches off what the template's settings.einvoice declares, for
this request. Asked for on an image output it answers 400 invalid_request. A plan
without e-invoices, or a day's test e-invoices used up, answers 403 forbidden with
feature: einvoice.
- 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.
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]
en16931ZUGFeRD 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]
factur-xboth 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]
embeddedWhat 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]
warnPDFs appended after this document, in order: render ids (rnd_…) of succeeded PDF renders stored in the region this render runs in, or PDFs of the workspace library by name (such as terms.pdf) or file id (fil_…). Each up to 100 characters. Not with settings.pdf.ua. The appended pages are not metered again.
Possible values: >= 1, <= 49
watermark object
Either a text or an image from the workspace library, not both; drawn as POST /pdf/watermark draws it.
The text, 1 to 200 characters of Latin, Greek or Cyrillic script.
Possible values: non-empty and <= 200 characters
A PNG or JPEG of the workspace library, by name (such as logo.png) or file id (fil_…).
Possible values: <= 200 characters
From 0 (invisible) to 1 (opaque).
Possible values: >= 0 and <= 1
0.2Degrees clockwise as in CSS, -360 to 360. Left out, a text runs diagonally (-45) and an image stands upright (0).
Possible values: >= -360 and <= 360
Hex colour of the text; grey (#737380) by default, ignored for an image.
Possible values: Value must match regular expression ^#?[0-9a-fA-F]{6}$
password object
Encrypts the PDF with AES-256, always as the last step. Send at least one of its fields. Not with an e-invoice.
Needed to open the document. No line breaks.
Possible values: non-empty and <= 127 characters
Lifts the restrictions; a random one nobody knows when omitted. No line breaks.
Possible values: non-empty and <= 127 characters
What a reader without the owner password may do. Left out, all four are allowed; [] allows none.
Possible values: [print, copy, modify, annotate], <= 4
storage objectnullable
The copy for the workspace's own bucket (bring your own storage). Left out, every output is
copied under the connection's key template. false leaves this document out. key names its
object below the connection's prefix instead of the key template: relative, without . or ..
segments, at most 1024 bytes; an existing object is overwritten. A render with its own key is
never answered from the dedup cache, and one without a connection answers 409
storage_not_configured. In a batch, each item carries its own.
- boolean
- object
Possible values: [false]
{
"template": "invoice-de",
"version": "published",
"html": "string",
"url": "string",
"engine": "jinja2",
"data": {},
"output": "pdf",
"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": {}
},
"filename": "invoice-2026-0042.pdf",
"expires_in": 0,
"access": "public",
"mode": "sync",
"locale": "string",
"webhook_url": "string",
"webhook_secret": "string",
"meta": {},
"region": "eu",
"dedupe": true,
"canary_key": "customer-4711",
"validate_data": false,
"post": {
"einvoice": {
"profile": "en16931",
"flavour": "factur-x",
"xml": "embedded",
"display_check": "warn"
},
"merge_after": [
"string"
],
"watermark": {
"text": "string",
"image": "string",
"opacity": 0.2,
"rotation": 0,
"color": "string"
},
"password": {
"user": "string",
"owner": "string",
"permissions": [
"print"
]
}
},
"storage": false
}