Skip to content
PDF API · Use case

Set the paper size, margins and orientation of any URL to PDF

Set the PDF paper size, the margins and the orientation per request, so the same endpoint prints an A4 report, a Letter memo, a landscape dashboard or a receipt-sized ticket. A PDF is a printed layout decision: which paper, how much whitespace, portrait or landscape, how much content per page. The PDF API exposes each of those as an option.

Start with the PDF API
The problem

One default PDF paper size cannot fit every document

A wide dashboard printed portrait gets crushed into a column. A receipt on A4 wastes most of the sheet. A long article with almost no margin is unreadable once it reaches a printer, and a US customer expects Letter where a European one expects A4.

Browsers pick one default and hide the rest behind a print dialog, which is no help to a backend job. CSS @page rules only work when you control the target page, and most HTML-to-PDF libraries make you restate the layout in their own configuration for every document type.

Microlink’s PDF options map straight to the printed layout: pdf.format for standard paper, pdf.width and pdf.height for exact dimensions, pdf.margin per side, pdf.landscape for wide content, pdf.scale to fit more or less per page, and pdf.pageRanges to keep only the pages you want.

Open a landscape Letter PDF of a wide page
How it works

How to set PDF paper size, margins and orientation

Use one sizing strategy at a time: a named format for office documents, or width and height for custom media. Margins, orientation and scale compose with either. The page size and layout guide has a live example of each option.

1 · Standard paper with margins
import createClient from 'microlink.io'

const microlink = createClient({
  apiKey: process.env.MICROLINK_API_KEY
})

const { url } = await microlink.pdf('https://example.com/report', {
  format: 'A4',
  margin: { top: '12mm', bottom: '16mm', left: '10mm', right: '10mm' }
})

A4 with asymmetric margins is the common setup for printed reports: extra room at the bottom for page numbers or binding. In the SDK the PDF options are flat; in a raw URL they use dot notation such as pdf.format=A4.

2 · Landscape, scaled, first pages only
import createClient from 'microlink.io'

const microlink = createClient({
  apiKey: process.env.MICROLINK_API_KEY
})

const { url } = await microlink.pdf('https://example.com/dashboard', {
  format: 'Letter',
  landscape: true,
  scale: 0.8,
  pageRanges: '1-2',
  printBackground: true
})

Landscape stops a wide table from being squeezed, scale 0.8 enlarges the content over the 0.6 default, and pageRanges keeps a two-page preview. printBackground includes background colors and images in the output.

3 · Custom paper as a URL
curl 'https://api.microlink.io/?url=https%3A%2F%2Fexample.com%2Fticket&pdf.width=80mm&pdf.height=200mm&pdf.margin=4mm&meta=false'

Exact dimensions for receipts, labels or tickets, expressed in px, in, cm or mm. meta=false skips metadata extraction, which is usually the biggest speedup for a PDF-only request.

Parameters used
  • pdf.format Letter, Legal, Tabloid, Ledger or A0 to A6. Default A4.
  • pdf.width Custom paper width with a unit; use it with height instead of format.
  • pdf.height Custom paper height with a unit.
  • pdf.margin One value for all sides or an object with top, right, bottom and left. Default 0.35cm.
  • pdf.landscape Landscape orientation for wide tables, dashboards and comparison pages.
  • pdf.scale Rendering zoom between 0.1 and 2. Default 0.6.
  • pdf.pageRanges Pages to keep, such as 1-5, 8, 11-13 or 5- for an open end. Out-of-range values fail with EPAGERANGE.

Units are the CSS ones: px, in, cm and mm. Layout options shape the paper, not the page, so pair them with mediaType when you need the on-screen design instead of the print stylesheet.

Why it works

Why paper size and margins belong in the request

Paper decisions change per document, not per integration. Passing them per request keeps one endpoint serving every format, from invoices to A0 posters.

01 · Format or dimensions
Named paper for offices, exact paper for everything else.
Reports, contracts and memos want A4, Letter or Legal so they print as expected. Receipts, labels, certificates and tickets want exact millimeters. Both are one option, and neither needs a template.

Formats and custom sizes are alternatives by design; pick the one that expresses what the document is.

02 · Whitespace and orientation
Margins and landscape make a page printable.
Per-side margins leave room for binding, a letterhead or a footer. Landscape stops wide comparison tables and dashboards from being squeezed into a portrait column.

The default margin is 0.35cm, which suits screen viewing; move to 1cm or more for anything that reaches a printer. For charts that render late, combine landscape with the waits in PDFs of JavaScript-rendered pages.

03 · Density and length
scale and pageRanges control how much you print.
Lower scale values fit more content per page; higher values enlarge it and add pages. pageRanges keeps only the pages you need, which is how previews and partial exports stay small.

When not to: if the page itself is not paginated content, such as an infinite feed, a screenshot with fullPage may represent it better than a PDF.

FAQ

Which PDF paper formats are supported?

Letter, Legal, Tabloid, Ledger and A0 through A6. A4 is the default when you pass no format. For anything else, such as a receipt roll or a badge, pass pdf.width and pdf.height with a unit.

Can I set different PDF margins per side?

Yes. pdf.margin accepts a single value for all sides or an object with top, right, bottom and left, each with a unit such as 12mm or 0.5in. The default is 0.35cm on every side.

How do I export only some pages of the PDF?

Use pdf.pageRanges with a string such as 1-3 or 1-5, 8, 11-13; leave the end open, as in 5-, to print through the last page. Ranges outside the document fail with the EPAGERANGE error code.

What does pdf.scale change in the generated PDF?

It zooms the rendered page before printing, from 0.1 to 2 with 0.6 as the default. Smaller values fit more content per page; larger values make it bigger and increase the number of pages. Very long documents that cannot finish in time fail with EPDFTOOLARGE, and a smaller scale is the documented fix.

How do I create a PDF with a custom page size, like a receipt or a label?

Pass pdf.width and pdf.height instead of pdf.format, each with a unit: px, in, cm or mm. An 80mm by 200mm page with a 4mm margin matches a thermal receipt, and the same approach covers certificates and shipping labels.
Related use cases

Solve the next problem with the same API

Clean PDFs without ads or banners

Get a document, not a browser tab: ads and consent popups blocked by default, sticky chrome removed with one CSS rule.
Export clean PDFs 

PDF invoices from authenticated pages

Print the invoice page your app already renders: forward the session, hide the chrome, name the file.
Generate PDF invoices 

PDFs of JavaScript-rendered pages

Print dashboards and single-page apps after they render: wait for the chart, open tabs and sections, then print.
Render dynamic pages to PDF 

Ready to print on the right paper?

Format, margins, orientation and scale in one request. Start on the free tier and print your first A4 or Letter document today.

Print with custom paper