Pick the invoice PDF renderer by asking which failure you can least afford: a layout that drifts on page two, or a render bill that climbs with every order. Fidelity and render cost pull in opposite directions, and the alternative you land on — a browser you run, a hosted render API, a template service — follows from that answer rather than from a feature grid.
Logistics makes the tension concrete.
A freight invoice isn't a receipt. It carries a block per shipment leg, fuel surcharges, customs references, a signature area, and, for public-sector buyers in the EU, a structured payload a machine has to read back out. Column headers repeat on page two. Totals sit in a fixed spot because somebody's accounts-payable robot is looking there. Run a few thousand of those overnight and the CPU you spend on layout stops being a rounding error — it turns into an infrastructure line nobody can attribute to any single customer.
The pipeline, in one line: order rows → HTML or a template → renderer → PDF bytes → object storage → a signed link on the invoice record.
Five ways to fill the middle box:
| # | Pattern | Fidelity ceiling | Where the cost lands | Public examples |
|---|---|---|---|---|
| 1 | Headless browser you operate | the CSS that engine implements | your CPU and RAM, per render | Gotenberg, a Puppeteer worker |
| 2 | Hosted HTML-to-PDF API | the engine the vendor ships | per document, no ops | DocRaptor, PDFShift, api2pdf |
| 3 | Template service with a JSON payload | the editor's component set | per document, plus layout lock-in | PDFMonkey, Carbone |
| 4 | Typesetting engine | full Paged Media, tagged output | licence plus CPU | PrinceXML, WeasyPrint |
| 5 | Direct assembly in code | whatever you draw yourself | engineering hours | pdf-lib, ReportLab |
1. Print it in a headless browser you run yourself
A headless browser prints the same markup your portal already renders. That's the appeal: one template, two outputs, no second layout language to keep in sync. Print emulation applies the print media queries, @page sets sheet size and margins, and page-break-inside: avoid stops a shipment leg from being sliced across a page boundary.
The cost is process-shaped. Every render holds a browser process with its own renderer thread and its own memory arena, so concurrency is capped by RAM long before it's capped by CPU — eight parallel renders on a 2-vCPU box will queue, and queueing at month-end is exactly when finance notices. That's the price of running a full layout engine per document.
Pick this when the invoice is mostly a table and your team already writes CSS.
2. Hand the same HTML to a hosted render API
Same markup, someone else's fleet. A hosted render API turns capacity into a per-document line item, which matters more than it sounds for freight billing, where volume arrives in month-end spikes rather than a flat stream. Nobody on your side patches a browser at 2am.
You give up the engine, though. Your fidelity ceiling becomes a roadmap item on a company you don't control, and debugging a layout difference means reproducing it through an API boundary instead of opening DevTools. One of these services documents a commercial typesetting engine rather than a browser as its renderer, which is why its paged-media coverage runs wider than a Chromium-based one.
Pick this when render volume is spiky and the layout is stable.
3. Move the layout into a template service
Here the invoice design leaves your repository and lives in a hosted editor. Your API call becomes a JSON payload of order data, and someone in billing operations adjusts the footer without opening a pull request. For a lot of logistics teams that's the honest answer — layout churn comes from finance, not from engineering.
What crosses the wire is order data, not markup: shipment legs, surcharge codes, a currency, an issue date. That's a cleaner contract than shipping a rendered string, and it survives a redesign, since the payload keeps its shape while the layout changes underneath it.
The catch is versioning. A template edit ships instantly, to production, with no review and no diff, and an invoice reprinted next year may not match the one the customer received. If you go this way, snapshot every rendered PDF into your own storage at issue time and treat the stored bytes as the record of truth.
4. Typeset it when the invoice has to survive an audit
Archive-grade output is a different job. PDF/A-3 permits file attachments, which is how the hybrid e-invoice formats in France and Germany carry a machine-readable XML invoice inside a human-readable PDF, and Directive 2014/55/EU is what pushed those semantics onto public-sector buyers across the EU. Tagged structure for accessibility, embedded font subsets, running headers built from Paged Media margin boxes — a dedicated typesetting engine implements more of that model than browser engines do.
Pick this when a regulator, not a customer, is the reader.
5. Build the PDF straight from the order object
No HTML at all. A PDF library lets you place text, lines and images against the coordinate system described in ISO 32000-2, the PDF 2.0 specification.
It's excellent for stamping, merging, appending a proof-of-delivery scan to an existing invoice — all cheap operations, since nothing gets laid out twice. It's miserable for anything with reflowing tables, and I wouldn't hand a multi-page freight invoice to it. Most teams land here as a second stage rather than a first one: render the document with one of the four patterns above, then assemble the final file in code.
So which invoice PDF API should a logistics team actually pay for?
Decide with a rule you can compute, not a preference. If the per-document cost of a hosted call is below what the same render costs on your own hardware — including the engineer-hours to keep that hardware patched — hosted wins. If invoice volume is steady and high, self-run wins, because you're paying wholesale for CPU you'd otherwise rent retail.
That arithmetic needs a number most teams don't have.
Before: a monthly compute bill, no idea which invoices are expensive. After: one record per render, written next to the bytes. Start by making the renderer a port, so switching pattern is a config change instead of a migration:
export type Invoice = {
id: string; // "INV-2026-004417"
orderId: string;
legs: { from: string; to: string; weightKg: number; charge: number }[];
currency: "EUR" | "USD";
};
export interface PdfRenderer {
readonly name: string; // "self-hosted-chromium" | "hosted-api" | "template-service"
render(html: string, opts: { pageSize: "A4" | "Letter" }): Promise<Uint8Array>;
}
Then wrap every implementation in the same telemetry. Duration, bytes, page count, attempt — four fields, and they answer almost every cost question you'll be asked later:
import { performance } from "node:perf_hooks";
export type RenderRecord = {
invoiceId: string;
renderer: string;
ms: number;
bytes: number;
pages: number;
attempt: number;
ok: boolean;
};
export async function renderInvoice(
renderer: PdfRenderer,
invoice: Invoice,
html: string,
emit: (record: RenderRecord) => void,
): Promise<Uint8Array> {
const started = performance.now();
for (let attempt = 1; attempt <= 2; attempt++) {
const base = { invoiceId: invoice.id, renderer: renderer.name, attempt };
try {
const bytes = await renderer.render(html, { pageSize: "A4" });
emit({ ...base, ms: Math.round(performance.now() - started), bytes: bytes.byteLength, pages: countPages(bytes), ok: true });
return bytes;
} catch (err) {
emit({ ...base, ms: Math.round(performance.now() - started), bytes: 0, pages: 0, ok: false });
// A second attempt covers a lost connection; a third would just re-run a layout error.
if (attempt === 2) throw err;
}
}
throw new Error("unreachable");
}
One NDJSON line per invoice is enough to answer the question the table above only estimates:
jq -s 'map(select(.ok))
| { renders: length,
cpu_seconds: (map(.ms) | add / 1000),
megabytes: (map(.bytes) | add / 1048576),
pages: (map(.pages) | add) }' render-log.ndjson
Multiply cpu_seconds by your instance price and you have a real cost per thousand invoices, comparable against any hosted quote on the same page count. Alert on cost per document, not on render latency — latency degrades quietly, but a template change that doubles page count shows up in the cost series within one batch.
Where each of these breaks
Fonts break first. A font that resolves on a developer laptop and falls back inside a container shifts every column, and the PDF is still valid, still 200-something kilobytes, still silently wrong — so pin embedded subsets and fail the render when a glyph is missing rather than after the customer calls.
Byte-level determinism breaks second. Every PDF carries a creation timestamp and a file identifier, so two renders of the same invoice never diff to zero. Golden tests have to rasterize a page and compare images, with a tolerance; comparing raw bytes gives you a permanently red build.
Concurrency breaks third, and it breaks on a schedule. Invoice runs are bursty by nature — a nightly batch, a month-end close — so the queue depth in front of the renderer matters more than the average render time you see on a quiet Tuesday. Record queue wait separately from render duration. When the two get confused, every capacity decision after that is guesswork.
Then there's the tail nobody budgets for: a customer who wants the logo three millimetres higher. Hosted APIs and template services aren't a good fit when layout demands arrive weekly from twelve different shippers, because each round trip is a support ticket instead of a CSS commit. Stick with a renderer you operate when layout is a product surface. Move to a service when it's a settled artifact.
I'm not sure there's a stable answer on cost, honestly — per-document prices move, and instance prices move faster. Your mileage may vary by page count more than by vendor. The measurement, though, outlives all of it: with a render record per invoice you can re-run the comparison in an afternoon, whichever way the market moved in 2026.
Top comments (0)