# Invoice PDF from HTML: a recipe card

> An invoice from HTML to an A4 PDF in one request: the HTML, the call, and a test of 41 invoices that shows which print CSS rules matter.

Recipe card by Serghei Pogor, founder of CurlShot (https://curlshot.com/about/serghei-pogor). Published 7 November 2026. Page for people: https://curlshot.com/blog/invoice-pdf-from-html

Send the invoice HTML in the html field of a POST request to CurlShot with format=pdf, pdf_paper_format=a4 and pdf_margin=15mm, from your server, and save the answer as a .pdf file. Two print rules matter for invoices that run past one page. Put the header row in a thead, so that it repeats: without it, the header printed on page 1 only in 36 of 36 test invoices. Put the totals in one block with break-inside: avoid, which fixed all 5 cut totals in a test of 41 invoices on 6 November 2026.

## Key facts

- One request does the job: the invoice markup goes in the html field, with format=pdf, an A4 page and a 15 mm margin. Keep the key on your server.
- A header row repeats on every page only when it is in a thead. In the test of 6 November 2026, a header row in the tbody printed once in 36 of 36 multi-page invoices.
- The totals were cut apart in 5 of 41 invoices, each time the last line item filled a page. One block with break-inside: avoid fixed all of them.
- tr { break-inside: avoid } changed nothing in the test, because Chromium kept every three-line row whole. Taller rows were not tested.
- A request with both html and url is refused, and each successful render counts as one screenshot of the plan of CurlShot.

## The card

**Makes:** one A4 PDF invoice. **Time:** about 10 minutes. **Needs:** an access key and a server to run one request.

- **One HTML file, invoice.html.** A real table with a <thead>, and the totals in one block. The listing above is complete.
- **An access key.** The Free plan has 100 screenshots a month and needs no card. Each successful render counts as one.
- **A place on your server to run the call.** The key must never be in a web page. A script, a job or a route handler is enough.
- **A way to build JSON.** jq on the command line, or JSON.stringify and json.dumps in code. Never paste the HTML into a string by hand.
- **Three options.** format=pdf, pdf_paper_format=a4 (the default, written out) and pdf_margin=15mm, because with no margin the text runs to the paper edge.

## The HTML

```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 request

```bash
# 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
```

```javascript
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)
```

The requests follow the documentation of CurlShot and were not sent in this run.

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

## A test of 41 invoices

On 6 November 2026, 41 invoices of 5 to 45 line items were each printed in 5 variants, 205 PDFs in all. 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. The API of CurlShot was not part of this test. 38 of the 41 invoices ran past one page.

| Variant | What it is | Rows cut in two | Totals cut apart | Page without header row |
| --- | --- | --- | --- | --- |
| Plain | Header row inside <thead>, no extra CSS. | 0 of 41 | 5 of 41 | 0 of 36 |
| No thead | The header row is the first row of <tbody>. | 0 of 41 | 1 of 41 | 36 of 36 |
| Rows kept whole | As Plain, plus tr { break-inside: avoid }. | 0 of 41 | 5 of 41 | 0 of 36 |
| Totals kept whole | As Plain, plus .totals { break-inside: avoid }. | 0 of 41 | 0 of 41 | 0 of 36 |
| Both rules | Plain, plus both break-inside rules. | 0 of 41 | 0 of 41 | 0 of 36 |

What the numbers say:

- The `<thead>` is what repeats the header row. Without it, 36 of 36 invoices lost it on every page after the first.
- Keeping the totals whole fixed all 5 cut totals. They were cut at 8, 18, 27, 36, 45 line items, where the last row fills a page. [1]
- `tr { break-inside: avoid }` changed nothing. Chromium kept all rows whole, which were three lines tall, without it. Much taller rows were not tested.
- What stays: with the totals rule on, 6 of 41 invoices end with a last page that holds only the totals. The test does not fix that.

## If it comes out wrong

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

## Variations

- US paper: `pdf_paper_format=letter`.
- Write the invoice in Markdown and send it in the `markdown` field.
- A receipt that is read on a screen: `pdf_fit_one_page=true` gives one page as tall as the content.

Start on the Free plan, which needs no card: see [pricing](https://curlshot.com/pricing). The rules for markup are on [HTML and Markdown input](https://curlshot.com/docs/html-and-markdown), and the PDF options on [PDF rendering](https://curlshot.com/docs/pdf).

## Questions

### 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": https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/break-inside (checked 6 November 2026)

## Go deeper

- [HTML to PDF](https://curlshot.com/tools/html-to-pdf)
- [Markdown to PDF](https://curlshot.com/tools/markdown-to-pdf)
- [HTML and Markdown input](https://curlshot.com/docs/html-and-markdown)
- [PDF rendering](https://curlshot.com/docs/pdf)
- [Pricing](https://curlshot.com/pricing)

## Read next

- [Web page to PDF: paper sizes, margins, print CSS](https://curlshot.com/blog/web-page-to-pdf-paper-sizes.md): Paper 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.
- [HTML to image: six templates you can copy](https://curlshot.com/blog/html-to-image-templates.md): Six 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.
- [Capture a web page as evidence that holds up](https://curlshot.com/blog/web-page-as-evidence.md): A 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.
