The shape of the page / options.margin
Set PDF margins in an API request
One value for all four sides, or an object naming each side, defaulting to 1cm all round.
What it is for
The page margin is the unprintable border around the content area, and it is not the same thing as a margin on the body element. Setting it here keeps it out of the stylesheet, which is useful when the same markup is rendered at different sizes for different recipients.
The request
Sent to options.margin. Everything else on this page is what happens around it.
{
"html": "<!doctype html>...",
"options": {
"margin": { "top": "18mm", "bottom": "20mm", "left": "16mm", "right": "16mm" }
}
}
// Or the same on every side:
// "margin": "18mm"The actual limits
Read from the implementation rather than remembered, so these are the numbers the API enforces rather than the ones a roadmap intends.
- A string sets all four sides. An object may name top, bottom, left and right; any side left out falls back to 1cm rather than to zero.
- The default when margin is omitted entirely is 1cm on every side.
- Setting a header or footer widens the corresponding margin from 1cm to 2cm automatically, so the running content has somewhere to go.
- Units follow CSS: mm, cm, in and px are all accepted. Prefer a print unit, because px converts at 96 to the inch and rounds.
What failure looks like
There is no validation failure here to speak of, and that is the problem worth knowing about: a margin below roughly 5mm is inside the unprintable border of most desktop printers, so the document renders correctly and is clipped when someone prints it. Nothing in the render pipeline can tell you that.
When this is the wrong tool
When the document has a first page that needs different margins from the rest, such as a letterhead. This option sets one margin for every page. Two page masters, through @page and @page :first in the document's own CSS, is the only way to express that, and it needs prefer_css_page_size.
Frequently asked
Is margins available on the free plan?
Yes. There is no plan gate on this one: it behaves the same on the free plan as on every paid plan, and the only limit that applies is the monthly document allowance.
Where do these numbers come from?
The running implementation. Every figure on this page, from payload ceilings to per-plan limits, is what the API enforces today rather than what a specification says it should. If one of them is wrong, the API is the thing to believe.
Related capabilities
Options that come up in the same request, and one from each of the other groups.
Set the PDF page size in an API request
Six named paper sizes, passed in the request options, with A4 as the default when nothing is given.
Generate a landscape PDF from an API
A boolean that turns the page rather than swapping its dimensions.
Scale PDF output from an API request
A multiplier applied to the whole rendered page, clamped between 0.1 and 2.
Use the CSS @page size instead of a format
Tells the renderer to use the page box the document declares rather than a named format, which is how every non-standard size is reached.
Render an HTML string to PDF over an API
Send a complete HTML document in the request body and get the PDF bytes back in the response.
Print background colours and images in a PDF
Controls whether background colours and images survive into the PDF. On by default here, which is the opposite of a browser's own default.
Render many PDFs in one API call
Up to several hundred documents in one request, each stored and returned as a link, with per-item success or failure rather than one all-or-nothing result.
Password protect a generated PDF
Encrypts the output so a reader is asked for a password before the document opens.
Everything the API does
The full list, grouped by which part of the request it belongs to.
API reference
The complete parameter documentation, including the parts with nothing interesting to say about them.
100 free documents a month, and a playground that runs a real render without a key.