Skip to content
Recipe cardBy 6 min read

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
6 stepsTested on 41 invoices

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.

invoice.html
<!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

It has no address of its own, so a relative path to a logo points nowhere. Every image, stylesheet and font needs a full 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

invoice.sh
# 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.pdf

Node.js

invoice.mjs
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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

VariantRows cut in twoTotals cut apartA page without the header row
PlainHeader row inside <thead>, no extra CSS.0 of 415 of 410 of 36
No theadThe header row is the first row of <tbody>.0 of 411 of 4136 of 36
Rows kept wholeAs Plain, plus tr { break-inside: avoid }.0 of 415 of 410 of 36
Totals kept wholeAs Plain, plus .totals { break-inside: avoid }.0 of 410 of 410 of 36
Both rulesPlain, plus both break-inside rules.0 of 410 of 410 of 36
  • The thead repeats the header

    With the header row in a thead it was on every page of all 36 invoices that had line items on two or more pages. With it in the tbody, 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: avoid on 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.

SymptomCauseFix
The header row shows on page 1 onlyIt 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 subtotalThe 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 missingThe 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 fontA 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 paperNo margin is added unless you ask.Set pdf_margin=15mm.
The request is refused with invalid_optionshtml 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.

Screenshot any page in one step

Paste an address into CurlShot and download the screenshot. A free account gives you 100 screenshots every month. No card needed.