How to Set PDF Page Size and Margins in PDFShift

Set PDFShift’s format option to a standard paper size such as A4 or Letter, or supply custom width and height dimensions with units. Set margin as a CSS-like shorthand string or as an object with separate top, right, bottom, and left values. The examples below use the documented options; check PDFShift’s current API documentation before relying on less common formats or units.

1. Choose a standard or custom page size

A standard format is simplest when the PDF should use a familiar paper size. The retrieved API reference lists Letter, Legal, Tabloid, Ledger, and ISO sizes A0 through A5. For a nonstandard sheet, provide a width and height with units; the reference extract lists inches, centimeters, and millimeters.

Need	Configuration approach
Common office paper	Choose a standard format, such as A4 or Letter.
Specific print dimensions	Set a custom width and height with explicit units.
Wide report or slide-like page	Use a suitable standard format or custom dimensions, then set landscape orientation if supported by your request setup.

For example, a custom size can be expressed as format: "210mm x 297mm" in a JSON request. That is dimensionally equivalent to A4; use the named format when a standard size is all you need. Confirm the exact custom-size syntax in the current API documentation, since the available option extract is a mirror.

2. Set margins with shorthand or per-side values

Use a shorthand string for uniform or symmetric margins. Use an object when a page needs different top, right, bottom, or left spacing.

Value	Effect
10px	10px on all four sides.
10px 0	10px top and bottom; zero left and right.
10px 0 20px	10px top, zero left and right, 20px bottom.
{"top":"12mm","right":"15mm","bottom":"18mm","left":"15mm"}	Explicit value for each side.

Keep units explicit and consistent with the intended output. A zero value can be written as 0; for nonzero values, use a length such as pixels, millimeters, or inches. Remember that margins reduce the area available to the page content.

3. Complete request examples

These examples show the layout fields in a PDFShift conversion request. Supply your PDFShift API credentials as required by your account and current API documentation; do not embed secrets in public client-side code.

JSON configuration

{
  "source": "https://example.com/report",
  "format": "A4",
  "margin": {
    "top": "12mm",
    "right": "15mm",
    "bottom": "18mm",
    "left": "15mm"
  }
}

For a custom sheet, replace "A4" with the custom width-by-height value supported by the current API, for example "210mm x 297mm". For equal margins, replace the object with "margin": "10mm".

cURL

curl -X POST "https://api.pdfshift.io/v3/convert/pdf" \
  -H "X-API-Key: YOUR_PDFSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://example.com/report",
    "format": "A4",
    "margin": "10mm 12mm"
  }' \
  --output report.pdf

Use the endpoint and authentication format shown in PDFShift’s current API docs for your account. If your integration already constructs the request body, the key settings are format and margin.

Python

import requests

api_key = "YOUR_PDFSHIFT_API_KEY"
payload = {
    "source": "https://example.com/report",
    "format": "A4",
    "margin": {
        "top": "12mm",
        "right": "15mm",
        "bottom": "18mm",
        "left": "15mm",
    },
}

response = requests.post(
    "https://api.pdfshift.io/v3/convert/pdf",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=90,
)
response.raise_for_status()
with open("report.pdf", "wb") as pdf_file:
    pdf_file.write(response.content)

Node.js

const response = await fetch('https://api.pdfshift.io/v3/convert/pdf', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_PDFSHIFT_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: 'https://example.com/report',
    format: 'A4',
    margin: {
      top: '12mm',
      right: '15mm',
      bottom: '18mm',
      left: '15mm',
    },
  }),
});

if (!response.ok) {
  throw new Error(`PDFShift request failed: ${response.status} ${await response.text()}`);
}

const pdf = Buffer.from(await response.arrayBuffer());
await import('node:fs/promises').then(({ writeFile }) => writeFile('report.pdf', pdf));

4. Account for headers, footers, and first-page overflow

Headers and footers need room inside the page layout. PDFShift says it applies margin space for a header or footer; when the first page already uses the full page height, that reserved space can push content onto the next page. The practical fix is to reduce the relevant margin or adjust the first page’s CSS while preserving any intentional whitespace.

If the document has a footer and only the first page needs the extra bottom space removed, PDFShift gives this example:

@page:first {
  margin-bottom: 0;
}

For a header that causes a top-margin issue:

@page:first {
  margin-top: 0;
}

These rules remove the named first-page margin. Set a nonzero value if the first page still needs some spacing. Also check whether the header or footer itself overlaps document content after changing the margin.

5. Control page breaks when the HTML cannot be changed

When a particular element should start on a new PDF page, use CSS page-break rules. PDFShift’s guide shows passing CSS in the conversion request to target an element. For example:

.chapter-start {
  break-before: page;
}

Apply the rule to the element that begins the next section. If you cannot edit the source HTML or stylesheet, use the request-level CSS facility described in the current PDFShift documentation. Check the generated PDF because content height, fonts, and header/footer space can affect where a break lands.

6. Troubleshooting

Symptom	Likely cause	What to change
Content spills onto an unexpected second page	The content fills the page, while header or footer space reserves additional margin.	Reduce the relevant margin or use a first-page @page:first override where appropriate.
Header or footer overlaps the body	The available page margin is too small for the header/footer content.	Increase the top or bottom margin and check the header/footer dimensions.
Custom dimensions are rejected or ignored	The value may not match the current API’s accepted custom-size syntax or unit set.	Try a documented standard format first, then verify custom width-by-height syntax and units against the current API reference.
Margins are not applied as expected	Shorthand ordering may be misunderstood, or a value may be invalid.	Use the documented CSS-like order, or switch to an object with all four sides explicit.
A section starts partway down a page	No page-break rule targets the section, or the rule targets the wrong element.	Apply break-before: page to the section’s starting element, using request CSS if the source cannot be edited.
The rendered PDF differs from browser expectations	Fonts, loaded assets, content height, or print CSS affect pagination.	Check the final PDF, ensure required resources are available to the converter, and simplify the page layout around the affected break.

7. Performance, reliability, and cost considerations

Page size and margins are layout settings; they do not by themselves guarantee a fixed page count or identical pagination across documents. Keep the source page’s print styles and assets stable, use explicit dimensions, and inspect representative PDFs when changing templates. Large images, slow page resources, and complex layouts can affect conversion time, so focus on the source document when a conversion is slow. Refer to PDFShift’s current service documentation for account-specific limits, pricing, and timeout behavior; the research available for this article does not establish those figures.

Or skip the browser setup

If the job is capturing a page as an image or PDF rather than configuring a PDFShift conversion, ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. Its API also supports PDF paper size, margins, landscape, and page ranges. See the ScreenshotNeo API docs.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free.

FAQ

Should I use millimeters or pixels for print margins?

Use a print-oriented unit such as millimeters or inches when you are matching physical paper requirements. Use pixels when your existing layout is defined in screen units and that choice fits the API’s accepted values.

Can I use different margins on the first page?

Yes. Use a first-page @page:first rule for the side that needs a different value, and retain any margin needed for readable content or header/footer clearance.

Does choosing A4 force the document to one page?

No. It sets the page dimensions. Content height, margins, and page-break rules determine how many pages the document uses.

When should I use per-side margins?

Use them when the header, footer, binding edge, or document design needs different spacing on each side. For equal margins, shorthand is easier to scan.