An invoice PDF from HTML
A recipe card for one job: your invoice markup in, a PDF out, in one request. Then a test of 41 invoices, so you know which print rules earn their place.
- Makes
- One A4 PDF invoice
- Time
- About 10 minutes
- Needs
- An access key and a server
Ingredients
Five things. Tick each one as you get it. None of them costs money on the Free plan, which has 100 screenshots a month and needs no card. See the plans.
0 of 5 ticked. Still to get: one HTML file, invoice.html, an access key, a place on your server to run the call, a way to build JSON, three options.
The HTML
Save this as invoice.html. It is the markup the test below used, cut down to two line items: a real table with a thead, and one block for the totals.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<style>
body { font: 14px/1.45 system-ui, sans-serif; color: #0f172a; margin: 0 }
table { width: 100%; border-collapse: collapse }
th, td { padding: 8px; border-bottom: 1px solid #e2e8f0; text-align: left; vertical-align: top }
th { background: #f1f5f9 }
.n { text-align: right; white-space: nowrap }
.totals { margin: 16px 0 0 auto; width: 260px; break-inside: avoid }
.totals p { display: flex; justify-content: space-between; margin: 0; padding: 4px 0 }
.totals .due { font-weight: 700; border-top: 2px solid #0f172a }
</style>
</head>
<body>
<h1>Invoice 2026-114</h1>
<p>Issued 2026-11-07 for Example GmbH</p>
<table>
<thead>
<tr><th>Description</th><th class="n">Qty</th><th class="n">Amount</th></tr>
</thead>
<tbody>
<tr><td>Monthly report, site 001</td><td class="n">1</td><td class="n">41.00</td></tr>
<tr><td>Monthly report, site 002</td><td class="n">1</td><td class="n">42.00</td></tr>
<!-- one <tr> per line item -->
</tbody>
</table>
<div class="totals">
<p><span>Subtotal</span><span>83.00</span></p>
<p><span>VAT 19%</span><span>15.77</span></p>
<p class="due"><span>Total due</span><span>98.77</span></p>
</div>
</body>
</html>The markup has to stand alone
https address that is reachable from the public internet. Read the rules on HTML and Markdown input.The request
Three options do the work: format=pdf, pdf_paper_format=a4 and pdf_margin=15mm. Run it on your server, never in a web page, because the key must stay private.
Command line
# Needs jq. The key stays in the ACCESS_KEY variable on your server.
jq -n --rawfile html invoice.html \
'{html: $html, format: "pdf", pdf_paper_format: "a4", pdf_margin: "15mm"}' |
curl -X POST "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d @- \
--output invoice-2026-114.pdfNode.js
import { readFile, writeFile } from 'node:fs/promises'
const html = await readFile('invoice.html', 'utf8')
const response = await fetch('https://curlshot.com/api/v1/screenshot', {
method: 'POST',
headers: {
'X-Access-Key': process.env.ACCESS_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({ html, format: 'pdf', pdf_paper_format: 'a4', pdf_margin: '15mm' }),
})
if (!response.ok) throw new Error((await response.json()).error_message)
const pdf = Buffer.from(await response.arrayBuffer())
if (pdf.subarray(0, 4).toString() !== '%PDF') throw new Error('The answer is not a PDF')
await writeFile('invoice-2026-114.pdf', pdf)Both requests follow the documentation and were not sent in this run. The test further down used a browser only. For US paper use pdf_paper_format=letter; to write the invoice in Markdown, send it in the markdown field. See PDF rendering.
The method
Write the table with a thead
Put the header row inside <thead>. In the test every page of every multi-page invoice repeated it. With the header row as the first row of <tbody>, it printed once, on page 1, in 36 of 36 invoices that ran past one page.
Put the totals in one block and keep it whole
Wrap Subtotal, VAT and Total due in one element with break-inside: avoid. Without it, the total was cut from the subtotal in 5 of 41 invoices, each time the last line item filled a page.
Escape every value that came from a person
A customer called Tom & <b>Jerry</b> is HTML to a browser. Replace &, <, >, " and ' with entities before a name or a line of text goes into the markup, or a name can break the table or run a script in the renderer.
Build the JSON body with a library
The HTML holds quotes, angle brackets and line breaks. Let jq or JSON.stringify escape them. Send exactly one source: a request with both html and url is refused with invalid_options.
Send it from your server and check the first four bytes
Post to the screenshot endpoint with the key in X-Access-Key. A good answer starts with %PDF. A refusal is JSON with error_message, so check the status before you write the file.
Open the PDF at the page edge
Send one invoice whose line count fills a page exactly, because that is where a total gets cut. In this layout it was 8, 18, 27, 36 or 45 lines. Look at the last two pages, not the first.
The taste test
41 invoices of 5 to 45 line items, each printed in 5 variants: 205 PDFs. 38 of the 41 ran past one page. Each cell counts invoices.
| Variant | Rows cut in two | Totals cut apart | A page without the header row |
|---|---|---|---|
| PlainHeader row inside <thead>, no extra CSS. | 0 of 41 | 5 of 41 | 0 of 36 |
| No theadThe header row is the first row of <tbody>. | 0 of 41 | 1 of 41 | 36 of 36 |
| Rows kept wholeAs Plain, plus tr { break-inside: avoid }. | 0 of 41 | 5 of 41 | 0 of 36 |
| Totals kept wholeAs Plain, plus .totals { break-inside: avoid }. | 0 of 41 | 0 of 41 | 0 of 36 |
| Both rulesPlain, plus both break-inside rules. | 0 of 41 | 0 of 41 | 0 of 36 |
The thead repeats the header
With the header row in a
theadit was on every page of all 36 invoices that had line items on two or more pages. With it in thetbody, it was on page 1 only, in 36 of 36.One rule fixes the totals
Without it the totals were cut at 8, 18, 27, 36, 45 line items: the last row filled a page (9 rows fit on each page after the first) and the totals started the next.[1] With
break-inside: avoidon the block, none were cut.The row rule changed nothing
tr { break-inside: avoid }made no difference: Chromium kept every row whole without it. The rows were three lines tall. Much taller rows were not tested, so keep the rule if yours can be.What the test did not fix
With the totals rule on, 6 of 41 invoices ended with a last page that holds only the totals. Moving the last row along with them was not tried.
If it goes wrong
Six things that spoil an invoice, what causes each, and the fix. The first two are measured above.
| Symptom | Cause | Fix |
|---|---|---|
| The header row shows on page 1 only | It is not inside <thead>. Measured: 36 of 36 multi-page invoices. | Move the header row into <thead>. |
| The total sits alone on the next page, apart from the subtotal | The totals are several loose elements, so a page can end between them. Measured: 5 of 41. | Wrap them in one element with break-inside: avoid. |
| The logo is missing | The markup has no address of its own, so a relative path points nowhere. Addresses on localhost or a private network are blocked. | Use a full https address that is reachable from the public internet. |
| The text is in a fallback font | A web font had not finished loading when the page was drawn. | Add wait_until=networkidle or a short delay. |
| The text touches the edge of the paper | No margin is added unless you ask. | Set pdf_margin=15mm. |
| The request is refused with invalid_options | html was sent with url or markdown, or selector or clip was sent with format=pdf. | Send one source, and no image-only options. |
For paper sizes, margins and page breaks in general, read the paper-size reference. To keep a PDF as a record of a page, read the evidence checklist. The HTML to PDF tool runs a first try without code, and pricing lists the plans.
How it was tested
On 6 November 2026, with Chromium 153.0.8010.12 driven by Playwright 1.63.0, and the PDFs read back with pdf.js (pdfjs-dist 6.5.438). Each invoice was one HTML page: a title, a table of line items with a three-line description each, and a block of totals. Chromium printed it to A4 with 15 mm margins and backgrounds on. Each PDF was then read back page by page with pdf.js to see which page held the header row, both ends of every row and each line of the totals.
A row counted as cut when its first line and its last line were on different pages. The totals counted as cut apart when the subtotal, the VAT line and the total were not all on one page. The header counted as missing when a page with line items did not hold it.
What the test did not cover: the API of CurlShot. Its requests are written from the documentation, and its PDFs were not read. The result is for the layout in this card; other row heights, fonts and paper sizes may behave differently.
Questions people ask
How do I turn an HTML invoice into a PDF with an API?
Send the markup in the html field of a POST request with format=pdf, and save the answer as a .pdf file. With CurlShot, add pdf_paper_format=a4 or letter and pdf_margin=15mm, and keep the access key in a header on your server.
Why does the table header not repeat on page 2 of my PDF?
The header row is probably not inside a thead element. In a test on 6 November 2026, a header row in the tbody printed on page 1 only in 36 of 36 invoices that ran past one page. With the row in a thead, every page had it.
How do I stop the total from splitting across two pages?
Put Subtotal, VAT and Total due in one element and give it break-inside: avoid. [1] In the test the totals were cut apart in 5 of 41 invoices without it, and in none with it.
Does the html field accept a logo or a web font?
Yes, if the address is a full https address that is reachable from the public internet. The markup has no address of its own, so a relative path points nowhere, and addresses on localhost or a private network are blocked. A web font may need wait_until=networkidle or a short delay.
Is the invoice PDF free to make?
Each successful render counts as one screenshot, and the Free plan of CurlShot has 100 a month without a card (read from the pricing page on 2026-11-06). See the pricing page for the paid plans.
Sources
- [1]MDN Web Docs, break-inside CSS property. Checked .
Read next
- ReferenceWeb page to PDF: paper sizes, margins, print CSSPaper sizes in millimetres, inches, CSS pixels and points, how margins and page breaks work in a PDF of a web page, and the print CSS that controls them.
- CookbookHTML to image: six templates you can copySix copyable HTML and CSS templates: social card, certificate, receipt, quote card, ticket and stat card, with sizes and the rules that make them render right.
- ChecklistCapture a web page as evidence that holds upA checklist for saving a web page as a credible record: what to capture, how to fix the time with a hash and timestamp, and what makes a screenshot weak.