DEV Community: PDFops

Merging a Letter invoice with an A4 attachment in pypdf, and the page size nobody normalizes

PDFops — Thu, 24 Sep 2026 13:07:36 +0000

pypdf's writer.append() concatenates PDFs page by page and copies each page's own /MediaBox along with it. Merge a US Letter invoice (612x792pt) with an A4 attachment (595x842pt) and the output has two page sizes, not one. Most viewers render that fine, each page at its own size. A print queue set to "same size as first page," a thumbnail generator, or a batch rasterizer that assumes one page size for the whole document can scale or crop the second page as if it were the first.

What /MediaBox actually is

/MediaBox is a rectangle stored per page inside a PDF's page tree, not once for the whole document. A PDF has no page-size property to read off the file as a whole; every page carries its own, and two pages in the same file are free to disagree. pypdf mirrors that structure. page.mediabox reads the page's own rectangle, and nothing in the library reconciles it against any other page already sitting in the writer.

Reproducing the mismatch

Build two single-page PDFs at different sizes and merge them with append(). Reading page.mediabox back off each page in the result shows exactly what went in: page 0 at 612x792, page 1 at 595.32x841.92. Nothing warns about the mismatch and nothing normalizes it, because normalizing was never part of the job append() does.

from pypdf import PdfReader, PdfWriter

invoice = PdfWriter()
invoice.add_blank_page(width=612, height=792)       # US Letter
invoice.write("invoice.pdf")

attachment = PdfWriter()
attachment.add_blank_page(width=595.32, height=841.92)  # A4
attachment.write("attachment.pdf")

merged = PdfWriter()
for path in ("invoice.pdf", "attachment.pdf"):
    merged.append(PdfReader(path))
merged.write("merged.pdf")

check = PdfReader("merged.pdf")
for i, page in enumerate(check.pages):
    print(i, page.mediabox.width, page.mediabox.height)
# 0 612.0 792.0
# 1 595.32 841.92

Why a viewer hides it and a rasterizer doesn't

A human scrolling through the merged file in Preview or Acrobat will not notice anything wrong. Each page renders at its own size, the way a PDF is supposed to. The trouble shows up one step downstream, in anything built around the assumption that a document has a single page size: a print dialog's "fit to same size as first page" option, a thumbnail grid sized off page one, a rasterizer that renders every page at one fixed DPI-and-dimension pair for a PNG export. Those tools scale or crop the second page to match the first, and an A4 attachment merged after a Letter invoice comes out stretched or clipped in exactly the places that matter.

Normalizing to one page size before merging

The fix is to normalize page size before merging, not after. Create a blank page at the target size, then merge the mismatched page's content onto it through a scale-and-center transform. pypdf's Transformation and PageObject.merge_transformed_page do the actual work; the function below just computes the scale factor that fits the source page inside the target rectangle without distorting its aspect ratio, and the translation that centers it.

from pypdf import PageObject, PdfReader, PdfWriter, Transformation

LETTER = (612, 792)

def fit_to_letter(page):
    src_w = float(page.mediabox.width)
    src_h = float(page.mediabox.height)
    scale = min(LETTER[0] / src_w, LETTER[1] / src_h)
    tx = (LETTER[0] - src_w * scale) / 2
    ty = (LETTER[1] - src_h * scale) / 2

    blank = PageObject.create_blank_page(width=LETTER[0], height=LETTER[1])
    transform = Transformation().scale(scale, scale).translate(tx, ty)
    blank.merge_transformed_page(page, transform)
    return blank

reader = PdfReader("attachment.pdf")
fixed_attachment = fit_to_letter(reader.pages[0])

writer = PdfWriter()
writer.add_page(PdfReader("invoice.pdf").pages[0])
writer.add_page(fixed_attachment)
writer.write("merged.pdf")

Run fit_to_letter on the A4 page before appending it and both pages in the merged output report 612x792. The attachment's content is scaled down slightly and letterboxed rather than stretched to fill a rectangle it was never drawn for, which is the difference between "smaller but legible" and "the wrong aspect ratio."

Try it

/api/merge concatenates pages the same way pypdf's append() does: each input page keeps whatever size it already had, and the endpoint does not resize anything for you. That is the correct default for most callers, since resizing without being asked would silently alter content nobody meant to touch. If you need one uniform page size in the output, normalize each page first with the transform above, then send the normalized files to /api/merge. A free key from /docs/signup covers 250 calls a month, and /api/inspect reads back page dimensions along with field names if you want to check sizes before merging rather than after.

Giving an AI agent PDF tools over MCP, and why it has to inspect before it fills

PDFops — Thu, 17 Sep 2026 13:05:32 +0000

MCP (Model Context Protocol) lets an agent call a tool directly instead of you writing the client code that calls an API on the agent's behalf. For PDF forms that convenience runs into the same problem pypdf developers hit by hand: a fill call needs the form's exact field names, and an agent guessing at them from a filename or a user's request gets it wrong in the same silent way a person does. pdfops-mcp handles this by shipping a tool whose entire job is answering "what fields does this PDF actually have," and documenting, in the tool description itself, that it has to be called before pdf_fill. An agent reads tool descriptions as instructions, not just documentation, so that ordering is enforced in the one place the agent actually reads.

What pdf_inspect gives the agent

pdf_inspect takes a PDF source and returns its AcroForm fields: name, type, options for a dropdown or radio group, current value, and a per-field maxLength where the PDF declares one. It also returns a fillTemplate object shaped exactly like what pdf_fill expects, so the agent has a paste-ready starting point instead of assembling one from the field list by hand. Run against a W-9 template, the response for one field looks like this:

{
  "name": "name",
  "type": "text",
  "maxLength": 60,
  "value": ""
},
{
  "name": "tax_classification",
  "type": "radio",
  "options": ["individual", "c_corp", "s_corp", "partnership", "llc", "other"],
  "value": ""
}

Neither of those names is guessable from "the W-9 form." A model filling this blind would reach for something like full_name or entity_type, both of which are wrong for this specific template and would fail the same way a hand-written script fails on a field name that doesn't exist. The tool description on pdf_fill spells this out directly: field names must exist in the PDF, values over a field's maxLength are rejected, and checkboxes take a plain "true" or "false" string rather than whatever on-state name the PDF happens to use internally.

Wiring it in

For Claude Code, adding the server is one command:

claude mcp add pdfops -- npx -y pdfops-mcp

Claude Desktop and Cursor take the same package through a config file instead:

{
  "mcpServers": {
    "pdfops": {
      "command": "npx",
      "args": ["-y", "pdfops-mcp"],
      "env": { "PDFOPS_API_KEY": "pdfops_live_…" }
    }
  }
}

The API key is optional. Without one the server runs on the keyless trial (100 requests per IP per month); a free key from /docs/signup raises that to 250 a month with no card. Either way the agent now has five tools: pdf_inspect, pdf_fill, pdf_merge, pdf_invoice, and pdfops_usage for checking remaining quota mid-session.

A two-step request, three tool calls

Ask the agent to "fill the W-9 at ~/docs/w9.pdf for the contractor and merge it with the signed cover sheet," and the tool sequence is pdf_inspect to read back the real field names, pdf_fill with those names to write the filled copy, then pdf_merge to combine it with the cover sheet in order. All three take plain file paths when the server runs next to the agent. npx pdfops-mcp under Claude Code or Claude Desktop starts as a local process over stdio, so it reads and writes the same filesystem the agent does, and the PDF bytes themselves never pass through the model's context window at all. The agent only ever sees field names, a confirmation string, and a path.

The part that breaks on a hosted server

That local-path convenience assumes the MCP server and the agent share a filesystem. Run the same server on a hosted gateway, such as Smithery, Glama's hosted mode, or a cloud IDE's remote MCP client, and ~/docs/w9.pdf stops meaning anything, because it names a path on the machine the agent is running on, not the machine the server is running on. A file path handed to a remote server just fails to open. pdfops-mcp's pdf_path and pdf_paths arguments accept an https:// URL or a data:application/pdf;base64,… URI as well as a local path, and every tool that produces a PDF returns it inline as an embedded resource whenever output_path is omitted, rather than assuming there's somewhere on that machine worth writing it. Nothing in the config changes between local and hosted mode: the server just checks what kind of string it got handed and resolves it accordingly.

Try it

The same pdf_inspect → pdf_fill → pdf_merge sequence is also three plain HTTP calls if you'd rather wire an agent up yourself: /api/inspect, /api/fill-form, and /api/merge, all under one X-API-Key header from a free key at /docs/signup. But for anything already running inside Claude Code, Claude Desktop, or Cursor, npx -y pdfops-mcp skips writing that client entirely: the agent just gets the tools.

Filling a checkbox with pypdf, and the on-state string it never validates

PDFops — Thu, 10 Sep 2026 13:13:17 +0000

pypdf's update_page_form_field_values() will set a checkbox's value without checking whether the value you passed means anything. Pass the wrong on-state string, one that doesn't exist anywhere in that field's appearance dictionary, and the call returns normally, the field looks filled if you read it back with get_fields(), and the box still renders unchecked in every viewer. No exception, no log line, not even at DEBUG level. Four common inputs trigger it: "Yes" without the leading slash, "true", "1", and the Python boolean True. Only the exact string the field's own appearance dictionary defines actually checks the box.

What actually decides whether a box looks checked

An AcroForm checkbox carries two things that have to agree: the field's value (/V) and the widget's appearance state (/AS). A viewer renders whichever appearance stream /AS points to, out of the ones listed in the widget's /AP /N dictionary. The PDF spec never mandates a name for the checked state. /Yes is the common convention because Acrobat's own form wizard writes it, but a PDF built in a different tool can use /On, /1, or a name its author chose. There is no universal on value for a checkbox, only whatever key sits in that specific field's own appearance dictionary next to /Off.

Reproducing the silent no-op

Take a one-field test PDF whose checkbox agree_to_terms really uses /Yes as its on-state, confirmed by reading _States_ off the field: ['/Off', '/Yes']. Running update_page_form_field_values() with auto_regenerate=False for the values "Yes", "true", "1", and True leaves /V and /AS at /Off every time, on pypdf 6.18.0. Only {"agree_to_terms": "/Yes"}, matching the field's real on-state string exactly, sets both to /Yes. The function returns None, so there is nothing in the call to check for success, and nothing gets logged either way.

from pypdf import PdfReader, PdfWriter

reader = PdfReader("consent-form.pdf")
writer = PdfWriter()
writer.append(reader)

# Every one of these looks reasonable. None of them checks the box.
for value in ["Yes", "true", "1", True]:
    writer.update_page_form_field_values(
        writer.pages[0], {"agree_to_terms": value}, auto_regenerate=False,
    )
    print(value, "->", writer.get_fields()["agree_to_terms"].get("/V"))
    # /Off, every single time. No exception, no warning.

# Only the field's own on-state string checks it.
writer.update_page_form_field_values(
    writer.pages[0], {"agree_to_terms": "/Yes"}, auto_regenerate=False,
)
print(writer.get_fields()["agree_to_terms"].get("/V"))  # /Yes

Reading the real on-state before you fill

The fix is to stop guessing at the on-state name and read it off the field instead. reader.get_fields() exposes it as _States_, a list where one entry is always /Off and the other is the string that actually checks the box; the widget annotation's own /AP /N keys carry the same string for anyone working at that lower level. Either way, the value passed to update_page_form_field_values has to come from the PDF itself, never from a hardcoded /Yes or a stringified boolean, because the on-state name belongs to that specific template, not to the file format in general.

reader = PdfReader("consent-form.pdf")
fields = reader.get_fields()

on_state = next(
    s for s in fields["agree_to_terms"]["/_States_"] if s != "/Off"
)

writer = PdfWriter()
writer.append(reader)
writer.update_page_form_field_values(
    writer.pages[0], {"agree_to_terms": on_state}, auto_regenerate=False,
)

The default that trades one bug for a viewer-dependent one

update_page_form_field_values defaults auto_regenerate to True, and that default sets NeedAppearances on the whole document's AcroForm dictionary rather than baking the checkbox's new appearance into the file at write time. NeedAppearances tells a conforming viewer to regenerate every field's appearance itself when the document opens, so rendering moves from decided once, at fill time, to decided per viewer, on every open. Acrobat honors the flag. A number of other renderers, including some used in headless pipelines, do not regenerate anything and just show whatever appearance stream was already baked in, which for a field filled this way can mean no visible change at all.

What that breaks beyond checkboxes

That reaches past checkboxes for anyone testing generated PDFs by hashing them. A document with NeedAppearances set can render two different ways depending on which engine opens it, and that undercuts the premise behind hashing a PDF and diffing it in CI: the bytes match, but a screenshot or a downstream re-render is not guaranteed to. auto_regenerate=False avoids planting that flag, at the cost of handling any appearance-stream work pypdf does not bake in on its own.

Try it

None of this is specific to a checkbox filled by hand. It is why /api/fill-form takes a plain "true" or "false" string for any checkbox field, resolves the real on-state name internally, and bakes a fresh appearance stream into the response PDF instead of setting NeedAppearances and leaving the outcome to whichever viewer opens the file next. A free key from /docs/signup covers 250 calls a month, and /docs/inspect reads back a template's real field names and types first, checkboxes included, so there is no need to go spelunging through _States_ by hand at all.

Packing-slip PDFs from a fulfillment webhook, and the redelivery that duplicates them

PDFops — Thu, 03 Sep 2026 13:08:55 +0000

A fulfillment webhook that fires when an order ships doesn't promise to fire exactly once. Most providers document at-least-once delivery, so a timeout on your side, a 5xx from a cold start, or a stray network blip triggers a retry with the same payload, sometimes seconds later, sometimes minutes. A packing-slip handler that calls PDFops fill-form on every delivery fills the same slip twice, burns quota twice, and sometimes emails a customer the same document twice. Fixing it takes one atomic claim on the event id, checked and set in a single round trip, so the second delivery learns someone already has it before doing any of that work again.

The shape of the job

Say a small 3PL runs packing slips off its warehouse system's order-shipped webhook: an order ships, the webhook fires with the order number, the shipping address, and the line items, and a Vercel Function fills a packing-slip template through PDFops, uploads the result to Vercel Blob, and returns the URL so the warehouse UI can show a print button. One order should produce one slip, no matter how many times the webhook decides to tell you about it.

At-least-once means sometimes-twice

Webhook providers rarely guarantee exactly-once delivery, because guaranteeing it would mean holding a distributed lock across every subscriber before confirming an event even landed. What they promise instead is at-least-once: if your endpoint doesn't answer with a fast 2xx, the event goes back into a retry queue and fires again, carrying the same event id and the same body. A five-second cold start on a rarely-hit Function, a transient 502 from your own upstream, or a provider retry policy that fires on any non-2xx response are each enough to trigger a second delivery of an event your handler already finished.

A single atomic claim, not two separate steps

The obvious first attempt reads: check a table for this event id, and if it's missing, do the work and insert a row. Under a single delivery that's correct. Under two deliveries that arrive close together, both requests can pass the check before either one finishes the insert, and both go on to call fill-form. The fix is to make the check and the reservation the same operation. A SET with NX (set only if the key doesn't already exist) is atomic in Redis, so exactly one of two concurrent requests gets back confirmation that it won the claim.

The handler

Everything above collapses into a route handler and a small helper, reachable from a Vercel Function over Upstash's REST API without pinning a TCP connection to a serverless invocation.

// app/api/webhooks/fulfillment/route.ts
import { Redis } from '@upstash/redis';
import { put } from '@vercel/blob';

const redis = Redis.fromEnv();
const PDFOPS_KEY = process.env.PDFOPS_API_KEY!;

export async function POST(req: Request) {
  const event = await req.json();
  // Field name varies by provider; use whatever id it signs on the event.
  const claimKey = `packing-slip:${event.id}`;

  const claimed = await redis.set(claimKey, 'in_progress', {
    nx: true,
    ex: 60, // clears itself if the handler crashes before finishing
  });

  if (claimed !== 'OK') {
    const state = await redis.get<string>(claimKey);
    if (state === 'in_progress') {
      // A concurrent delivery already owns this event; let the
      // provider's own retry backoff handle the wait.
      return new Response(null, { status: 409 });
    }
    // state holds the URL from a run that already finished.
    return Response.json({ url: state });
  }

  try {
    const url = await generatePackingSlip(event.order);
    await redis.set(claimKey, url, { ex: 60 * 60 * 24 * 30 }); // keep 30 days
    return Response.json({ url });
  } catch (e) {
    await redis.del(claimKey); // let the next redelivery try again
    throw e;
  }
}

async function generatePackingSlip(order: {
  number: string;
  shipTo: string;
  items: { qty: number; sku: string }[];
}): Promise<string> {
  const template = await fetch(process.env.PACKING_SLIP_TEMPLATE_URL!).then(
    (r) => r.arrayBuffer(),
  );
  const form = new FormData();
  form.set('pdf', new Blob([template], { type: 'application/pdf' }), 'template.pdf');
  form.set(
    'fields',
    JSON.stringify({
      order_number: order.number,
      ship_to: order.shipTo,
      items: order.items.map((i) => `${i.qty}x ${i.sku}`).join('\n'),
    }),
  );
  form.set('flatten', 'true');

  const res = await fetch('https://pdfops.dev/api/fill-form', {
    method: 'POST',
    headers: { 'X-API-Key': PDFOPS_KEY },
    body: form,
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`fill-form failed: ${err.error} (${err.details})`);
  }
  const pdf = await res.arrayBuffer();
  const blob = await put(`packing-slips/${order.number}.pdf`, pdf, {
    access: 'public',
    contentType: 'application/pdf',
  });
  return blob.url;
}

The claim key carries three possible states over its life: absent (no delivery has touched this event yet), in_progress (a delivery is mid-flight, held under a short expiry so a crash doesn't wedge it forever), and a stored URL (the run that finished, kept for a month so a very late redelivery gets the same answer instead of a second document). A redelivery that lands while the first is still working gets a 409 back; a redelivery that lands after success gets the URL straight back, with no call to fill-form made at all.

Releasing a claim that never finished

A handler that crashes mid-fill, say because the template fetch times out, leaves its claim in the in_progress state until the expiry clears it. That's why the TTL matters: pick it to comfortably exceed the slowest real run, short enough that a genuine crash doesn't block a legitimate retry for long. The catch block also deletes the claim directly on a known failure, so a clean error doesn't have to wait out the timer at all before the next delivery can try again.

Try it

The same claim pattern covers any webhook-triggered document: an invoice on payment succeeded, a contract on signature completed, a statement on billing cycle closed, anywhere a provider might redeliver an event your handler already finished. A free key from /docs/signup covers 250 calls a month, worth protecting from accidental doubles for exactly the reason above: a duplicate fill on a retried webhook is quota spent on a document nobody asked for twice. Check usage anytime at /docs/usage or the dashboard, and confirm a template's field names at /docs/inspect before wiring the fields object above to your own PDF.

Filling a PDF from a Python Lambda with no dependencies to package

PDFops — Thu, 27 Aug 2026 13:08:59 +0000

A Python Lambda that fills a PDF usually reaches for one of two things: a native library like pypdf, or the requests package wrapping an HTTP call. Both work, and both come with something to package: pypdf means owning appearance streams and checkbox on-state names yourself, and requests means installing a wheel into the deployment zip or a Lambda layer before the first invocation ever runs. Here's a fill that skips both, using only urllib.request and json from the standard library, plus a multipart body built by hand. Nothing to pip install, nothing to vendor, nothing to test against Amazon Linux's binary compatibility before it works in Lambda.

The shape of the job

Say a small insurance brokerage wants certificates of insurance generated on demand. A client hits an API Gateway endpoint with a policy number, the holder's name, and a coverage date; a Lambda function pulls a fixed COI template from S3, fills three AcroForm fields, and writes the result back to S3 for the client to download. The template stays the same from request to request. Only the values change.

Why the standard library is enough here

The friction with PDF work on Lambda tends to be the same friction twice, once for the PDF library and once for the HTTP client. A local fill library that flattens forms typically shells out to pdftk or poppler, and neither one ships in the Lambda runtime, so flattening turns into a container image or a custom layer just to run one binary. An HTTP client like requests isn't in the runtime either; it needs a pip install into the deployment package, and its compiled dependencies carry version quirks against Amazon Linux worth avoiding when a bare urllib.request call does the same job.

A single multipart POST to a hosted fill endpoint moves the PDF work off the Lambda entirely: the appearance streams, the checkbox states, and the flattening all run server-side, and the only local code is one HTTP request assembled from modules already sitting in every Python 3 Lambda runtime.

Building the multipart body by hand

multipart/form-data is a plain wire format: a boundary string repeated between parts, a Content-Disposition header naming each field, and the raw file bytes with no transfer encoding applied. Reproducing it without a library is short.

import uuid

def build_multipart(fields, file_bytes, filename):
    boundary = uuid.uuid4().hex
    parts = []
    for name, value in fields.items():
        parts.append(
            f"--{boundary}\r\n"
            f'Content-Disposition: form-data; name="{name}"\r\n\r\n'
            f"{value}\r\n"
        )
    parts.append(
        f"--{boundary}\r\n"
        f'Content-Disposition: form-data; name="pdf"; filename="{filename}"\r\n'
        f"Content-Type: application/pdf\r\n\r\n"
    )
    header = "".join(parts).encode("utf-8")
    footer = f"\r\n--{boundary}--\r\n".encode("utf-8")
    return header + file_bytes + footer, boundary

Three things worth pointing at. The field carrying the template is named pdf, matching the API's multipart schema exactly, a detail that's easy to get wrong copying from an example that used a different name. fields is a JSON string, not a nested multipart structure, so the whole dict gets json.dumps'd into one text part. And flatten travels as the literal string "true", since the endpoint reads it off a multipart field where there's no such thing as a JSON boolean.

The Lambda handler

The handler pulls the template from S3 once per invocation, fills it, and writes the result back under a fresh key.

import json
import os
import urllib.error
import urllib.request
import uuid

import boto3

BUCKET = os.environ["COI_BUCKET"]
TEMPLATE_KEY = "templates/coi-template.pdf"
API_KEY = os.environ["PDFOPS_API_KEY"]

s3 = boto3.client("s3")

def fill_certificate(holder_name, policy_number, effective_date):
    template = s3.get_object(Bucket=BUCKET, Key=TEMPLATE_KEY)["Body"].read()
    fields = {
        "fields": json.dumps({
            "holder_name": holder_name,
            "policy_number": policy_number,
            "effective_date": effective_date,
        }),
        "flatten": "true",
    }
    body, boundary = build_multipart(fields, template, "coi-template.pdf")

    req = urllib.request.Request(
        "https://pdfops.dev/api/fill-form",
        data=body,
        method="POST",
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": f"multipart/form-data; boundary={boundary}",
        },
    )
    try:
        with urllib.request.urlopen(req, timeout=25) as res:
            return res.read()
    except urllib.error.HTTPError as e:
        err = json.loads(e.read())
        raise RuntimeError(
            f"PDFops fill-form failed: {err['error']} ({err['details']})"
        ) from e

def handler(event, context):
    payload = json.loads(event["body"])
    pdf_bytes = fill_certificate(
        payload["holder_name"],
        payload["policy_number"],
        payload["effective_date"],
    )

    key = f"certificates/{uuid.uuid4().hex}.pdf"
    s3.put_object(Bucket=BUCKET, Key=key, Body=pdf_bytes, ContentType="application/pdf")
    url = s3.generate_presigned_url(
        "get_object", Params={"Bucket": BUCKET, "Key": key}, ExpiresIn=3600
    )
    return {"statusCode": 200, "body": json.dumps({"url": url})}

The error handling matters as much as the happy path. A non-2xx response raises urllib.error.HTTPError, and PDFops returns { "error": "", "details": "" } on failure, so parsing e.read() into JSON gets you the same error codes the docs list: invalid_api_key if the key in the environment variable got rotated by a later signup, rate_limited with a Retry-After header if the month's quota ran out, or unsupported_field_type if the template's field types changed under you. Surfacing err['error'] in the raised exception means CloudWatch shows which of those happened instead of a bare stack trace from inside urlopen.

Quota, and the shared-IP problem

PDFops allows 100 anonymous requests per IP per month before it needs a key. Lambda functions attached to a VPC often route outbound traffic through a shared NAT gateway, so that IP quota belongs to every function behind the same gateway, not just this one. A key sidesteps the sharing, since usage is tracked per key rather than per IP. POST /api/signup with an email address gets one; the key arrives by email rather than in the response body, so a debug print of the signup response can't leak it into a log. Store it as a Lambda environment variable and pass it as X-API-Key on every request; the free tier covers 250 requests a month, plenty for a brokerage that isn't yet issuing certificates by the hundred.

Try it

The pattern here works for any fixed-template, variable-value PDF: a permit, a receipt, a boarding pass. Sign up for a free key at /docs/signup, check what a template's AcroForm fields are named at /docs/inspect before assuming pdf matches your keys, and watch a key's monthly usage at /docs/usage or the dashboard.

Bulk-filling PDFs from a CSV, and the 429 you shouldn't retry

PDFops — Thu, 20 Aug 2026 13:09:00 +0000

Filling one PDF from a webhook is a solved problem already. Filling three hundred of them from a CSV export is a different job. The API call is identical to the single-fill case. What breaks is everything around it: running out of quota at row 340, or writing a retry loop for a rate limit that resets once a month instead of once a minute.

The shape of the job

Say a workshop cohort of 180 people just wrapped, and everyone gets a completion certificate with their name, the course title, and the date baked into a fixed PDF template. The roster is a CSV export from a registration tool, and the template has three AcroForm fields: attendee_name, course_name, completion_date. The goal is a folder of 180 filled PDFs, a log of which rows failed if any did, and a script that runs the same way next cohort.

Check the quota before you start

GET /api/usage returns tier, limit, used, remaining, and the UTC period it's counting. A free key gets 250 requests a month. Run 180 fills against a key that already used 150 this period, and the result isn't 180 clean failures, it's 100 finished certificates and 80 rows that died partway through a loop with no idea it was about to run dry.

The fix is one request before the loop starts: compare the row count to usage.remaining, and stop before a single file gets written if the batch doesn't fit. A partial run of certificates is worse than no run, because now someone has to work out by hand which 100 of 180 people already have one.

The script

import { readFile, writeFile, mkdir } from "node:fs/promises";

const API_KEY = process.env.PDFOPS_API_KEY;
const TEMPLATE_PATH = "./certificate-template.pdf";
const CSV_PATH = "./attendees.csv";
const OUT_DIR = "./out";
const CONCURRENCY = 5;

function parseCsv(text) {
  const [header, ...lines] = text.trim().split("\n");
  const cols = header.split(",").map((c) => c.trim());
  return lines.map((line) => {
    const values = line.split(",");
    return Object.fromEntries(cols.map((c, i) => [c, values[i]?.trim()]));
  });
}

async function checkQuota(rowCount) {
  const res = await fetch("https://pdfops.dev/api/usage", {
    headers: { "X-API-Key": API_KEY },
  });
  const usage = await res.json();
  if (usage.remaining < rowCount) {
    throw new Error(
      `Need ${rowCount} calls, only ${usage.remaining} left ` +
      `(resets ${usage.resets_at}). Not starting a run I can't finish.`
    );
  }
  console.log(`Quota OK: ${usage.remaining}/${usage.limit} left, ${rowCount} rows queued.`);
}

async function fillOne(template, row) {
  const form = new FormData();
  form.append("pdf", new Blob([template]), "template.pdf");
  form.append("fields", JSON.stringify({
    attendee_name: row.name,
    course_name: row.course,
    completion_date: row.date,
  }));
  form.append("flatten", "true");

  const res = await fetch("https://pdfops.dev/api/fill-form", {
    method: "POST",
    headers: { "X-API-Key": API_KEY },
    body: form,
  });

  if (res.status === 429) {
    const err = new Error("rate_limited");
    err.retryAfter = res.headers.get("retry-after");
    err.fatal = true;
    throw err;
  }
  if (!res.ok) {
    return { row, ok: false, error: `${res.status} ${await res.text()}` };
  }

  const bytes = Buffer.from(await res.arrayBuffer());
  const filename = `${row.name.replace(/\s+/g, "_")}.pdf`;
  await writeFile(`${OUT_DIR}/${filename}`, bytes);
  return { row, ok: true };
}

async function run() {
  const [template, csv] = await Promise.all([
    readFile(TEMPLATE_PATH),
    readFile(CSV_PATH, "utf8"),
  ]);
  const rows = parseCsv(csv);
  await checkQuota(rows.length);
  await mkdir(OUT_DIR, { recursive: true });

  const queue = [...rows];
  const results = [];

  async function worker() {
    while (queue.length) {
      const row = queue.shift();
      try {
        results.push(await fillOne(template, row));
      } catch (e) {
        if (e.fatal) {
          console.error(
            `Rate limited mid-run. Retry-After is ${e.retryAfter}s ` +
            `(next calendar month), not worth waiting out. ` +
            `${queue.length + 1} rows unprocessed.`
          );
          const rest = [row, ...queue];
          await writeFile(
            "./unprocessed.csv",
            rest.map((r) => `${r.name},${r.course},${r.date}`).join("\n")
          );
          process.exit(1);
        }
        results.push({ row, ok: false, error: String(e) });
      }
    }
  }

  await Promise.all(Array.from({ length: CONCURRENCY }, worker));

  const failed = results.filter((r) => !r.ok);
  console.log(`${results.length - failed.length}/${results.length} filled.`);
  if (failed.length) {
    console.log("Failed rows:", failed.map((f) => f.row.name).join(", "));
  }
}

run();

Five things worth pointing at. The template PDF is read from disk once and reused for every request. fields is a JSON string inside the multipart body, matching what the endpoint expects, and flatten is literally the string "true": the API reads it off a multipart field, so a JSON boolean fails the type check silently. Five workers pull from a shared queue instead of firing 180 requests at once, which keeps the concurrency under your own control rather than whatever the server or your terminal can absorb. And a failed row lands in the results array instead of throwing, so one malformed CSV line doesn't take down 179 good ones with it.

The 429 that isn't worth retrying

Every PDFops rate-limit response carries a Retry-After header, and the instinct on seeing a 429 is to write a backoff loop: wait, retry, wait longer. That instinct is right for most APIs and wrong for this one. Retry-After here is seconds until the next calendar month, because quota resets on a monthly period rather than a sliding window. Hit the limit on the 3rd and the header can read past two million seconds. A batch script that dutifully awaits that value looks like it's still working for three and a half weeks.

The right move on a 429 mid-run is to stop, log which rows didn't get processed, and exit. The pre-flight quota check above should make this unreachable in normal operation, but it's a real failure mode if two scripts share a key, or a teammate's run eats quota between your check and your last request landing.

Try it

The free tier covers a cohort of 250 through this exact script. Sign up for a key, drop a CSV and a PDF template next to it, and swap the three field names for whatever the template uses. Field-type mapping for checkboxes, dropdowns, and radio groups is at /docs/fill-form; quota semantics are at /docs/usage.

Automating PDF fills, merges, and invoices in n8n without a Function node

PDFops — Thu, 13 Aug 2026 13:06:51 +0000

Most n8n workflows that touch PDFs end up in the same place: an HTTP Request node with a hand-built multipart body, or a Code node calling pdf-lib and hoping the binary handling survives the next n8n upgrade. n8n-nodes-pdfops is a verified community node that turns PDF inspect, fill, merge, and invoice generation into typed n8n operations, with binary PDFs flowing in and out like any other node.

Installing it

On n8n Cloud, open the nodes panel and search "PDFops"; it installs in one click because it carries n8n's verified badge. Self-hosted, it's Settings → Community Nodes → Install, or from the CLI:

n8n community-node install n8n-nodes-pdfops

The node works with no credential at all, against the same 100-requests-per-IP-per-month anonymous tier the playground uses. Add a PDFops API credential (an API key in the X-API-Key header) once you want a higher quota or the usage operation described below.

The five operations

One node, five operations, picked from a dropdown: Inspect Fields lists a PDF's AcroForm field names, types, and current values, plus a fill template you can paste straight into the next node. Fill Form writes values into those fields and can flatten the result so it stops being editable. Merge concatenates every PDF on the incoming items, in item order, into one file. Generate Invoice renders a complete invoice PDF from a JSON object, no template required. Get Usage returns tier, quota, used, and reset date for a key. Fill, merge, and invoice are deterministic: run the same workflow twice on the same input and the output PDF is byte-identical, so a re-run never shows up as a spurious diff in whatever you archive it to.

A worked example: fill from a webhook, catch the typo first

The node ships with three ready-to-import workflow templates. The one worth walking through end to end is fill and flatten PDF forms from webhook data, because it solves the failure mode that makes "just fill the PDF" workflows unreliable: a field name typed wrong in the JSON payload doesn't error, it just fills nothing, and the caller gets back a document that looks correct until someone opens it.

The workflow receives a webhook carrying a PDF URL, an email address, and a fields object, validates the payload, then runs Inspect Fields on the blank PDF before it fills anything. A Code node diffs the requested field names against the real ones the inspect call returned. Any name that doesn't match routes straight to an error response, naming the bad field, instead of silently producing a blank form. Only a payload that passes the diff reaches Fill Form with flatten on, so the result can't be edited after it ships. From there it fans out: Gmail sends the filled PDF, Google Drive archives a copy, and the caller gets a JSON receipt.

Swap Gmail for SMTP or Slack and Drive for S3 without touching the PDF steps; none of them know or care where the file ends up.

Two more recipes, already built

Merge two forms into one packet. A workflow named onboarding packet from two PDF forms takes two blank PDF URLs and two field objects (a new-hire packet, a new-tenant packet, whatever your business fills in pairs), fills each with its own Fill Form node, waits for both branches, and joins them with Merge so the first form always lands as page one. It refuses to upload a packet unless both branches actually filled, so a partial run never produces a half-finished file that looks whole.

An invoice on every Stripe payment. A Stripe trigger on payment_intent.succeeded feeds a Code node that shapes the charge into invoice JSON, and this is the step where most hand-rolled invoice code breaks quietly: Stripe reports amounts in the smallest currency unit, but JPY, KRW, and thirteen other currencies don't have 100 of those units, so a reflexive amount / 100 issues an invoice a hundred times too small. The template checks the currency against a zero-decimal list before it divides. Generate Invoice renders the deterministic PDF, then it archives to S3, emails the customer when an address is on file, and logs a row to a spreadsheet ledger. A failed render posts to Slack with the payment ID, so a missing invoice gets noticed instead of just not existing.

Keyless works; a key gets you further

Every operation runs without a credential at the shared 100/IP/mo anonymous rate, the same limit the API enforces everywhere else. A free API key (250 requests/month, email in, key out, no card) raises that ceiling and is required for the Get Usage operation, which returns your remaining quota so a workflow can check headroom before it burns the month's last call. Paid tiers exist once a workflow outgrows 250 a month, but the free key runs a real production automation, not just a demo.

Try it

Search "PDFops" in the n8n nodes panel, or install n8n-nodes-pdfops self-hosted. The three templates above are importable as-is from the node's npm page; swap in your own PDF, Stripe account, or storage provider and the PDF steps don't change. Building on the raw API instead? Start at /docs or the OpenAPI spec.

Filling encrypted government PDFs: what actually works, measured

PDFops — Fri, 07 Aug 2026 13:46:06 +0000

You download an official blank from a court or tax site, it opens in every viewer without asking for anything, and then your code throws: Input document to PDFDocument.load is encrypted. There is no password to supply, because the file was published for the public. We ran two real forms in this class, California's FL-100 divorce petition and Canada's TD1 tax credits return, through seven independent fill tools and recorded exactly which ones cope.

Why a public form rejects your library

These blanks are AES-encrypted with an empty user password. The PDF spec allows a document to carry two passwords: a user password that gates opening, and an owner password that gates modification. Publishers set the user password to the empty string, so any viewer decrypts the file silently, and set a real owner password to discourage edits. Strict parsers see the encryption dictionary, notice they were given no credentials, and refuse the whole file. That is the correct reading of the spec and a useless outcome for you.

pdf-lib and its maintained fork @cantoo/pdf-lib both reject FL-100 and TD1 at load. The PDFops fill API is built on the same family and refuses too, with a 400 encrypted_pdf that tells you the workaround instead of leaving you to guess. pypdf opens both files directly when installed as pypdf[crypto], but writes text fields only. The full per-tool results live on the registry pages for ca-fl-100 and cra-td1.

The shell answer: pdftk fills them natively

The one mainstream tool that treats an empty user password like a viewer does is pdftk-java. It enumerated all 158 fields of FL-100, filled 148 of them (every text field, checkbox and radio group; the rest take no value by design), and re-reading its output confirmed all 148 values landed. Same story on TD1: 27 of 27. No decrypt step, and the output file comes out unencrypted.

# enumerate fields (works despite the encryption)
pdftk fl100.pdf dump_data_fields > fields.txt

# fill from an FDF file
cat > values.fdf <<'EOF'
%FDF-1.2
1 0 obj
<< /FDF << /Fields [
<< /T (FL-100[0].Page1[0].CaptionP1_sf[0].AttyInfo[0].AttyFor_ft[0]) /V (Jane Doe) >>
] >> >>
endobj
trailer
<< /Root 1 0 R >>
%%EOF
EOF
pdftk fl100.pdf fill_form values.fdf output filled.pdf

pdftk prints a warning about the owner password and carries on. The owner password restricts editing as a matter of policy, and pdftk takes the position that a file the public can open is a file the public can fill. Adobe's own tools take the stricter position. Know which side your compliance story needs before you rely on this.

The dump_data_fields trap

One gotcha cost us an hour and produces a convincing false negative. On forms that carry an XFA layer alongside the normal field tree, dump_data_fields prints two FieldValue lines per field: an empty one first, then the real value.

FieldName: FL-100[0].Page1[0].CaptionP1_sf[0].AttyInfo[0].AttyFor_ft[0]
FieldNameAlt: ATTORNEY FOR (name):
FieldFlags: 8388608
FieldValue:
FieldValue: Jane Doe

A verification script that greps the first FieldValue line reads an empty string, concludes the fill silently failed, and sends you debugging a problem that does not exist. Collect every FieldValue line for a field and check whether any of them matches what you wrote.

The in-process answer: decrypt first

If your fill runs inside a JS or Python service rather than a shell pipeline, remove the restriction up front with qpdf. The transformation is lossless: same pages, same fields, same appearance.

qpdf --decrypt fl100.pdf fl100-open.pdf

curl -X POST https://pdfops.dev/api/fill-form \
  -F "pdf=@fl100-open.pdf" \
  -F 'fields={"FL-100[0].Page1[0].CaptionP1_sf[0].AttyInfo[0].AttyFor_ft[0]":"Jane Doe"}' \
  -F "flatten=true" \
  -o filled.pdf

After the decrypt, the file behaves like any other AcroForm: pdf-lib loads it, the API fills and flattens it, and field values verify on re-inspection. In our runs this path landed every supported field on both forms.

How common is this class?

More common than two unlucky picks. After this post was drafted we extended the corpus to 22 forms, and five of them ship empty-password AES: FL-100 and FL-150 (so it is the California Judicial Council's house style, on 2 of 2 sampled), TD1 and T2200 (same for the CRA, 2 of 2), and SSA-89, the SSN verification consent signed in most US mortgage closings. pdftk filled all five natively; every pdf-lib-family tool refused all five. If your product touches court filings, Canadian tax paperwork or lending, you will meet this class.

The forms this does not save

Encryption is sometimes the smaller half of the problem. Every current USCIS form we sampled except the I-9 combines this same empty-password AES with a dynamic XFA body, which means the visible form is rendered from an embedded XML template rather than from the AcroForm field tree. qpdf gets you through the encryption, but fillers in the pdf-lib family then write the AcroForm layer and drop XFA on save, and pdftk inherits the same limits. For that class, plan on the AcroForm output being correct in mainstream viewers and blank in old XFA-first Adobe products, or use the agency's own e-filing channel.

PDFops v0.10: fill a PDF by email, make any PDF fillable

PDFops — Thu, 06 Aug 2026 15:04:05 +0000

v0.10 is the no-code on-ramps release. The API is unchanged — same two primitives, fill and merge — but there are now two ways to use PDFops before you've written a line of code, and one of the oldest dead-ends in PDF automation ("this PDF has no form fields") finally has a fix that doesn't involve Acrobat.

Fill a PDF by email — fill@pdfops.dev

Attach a blank fillable PDF and your field values to an email, send it to fill@pdfops.dev, and the reply comes back with the filled PDF — plus the exact curl command that produced it, so the jump from "it works" to "it's in my codebase" is copy-paste. Values go in the body as plain key: value lines, as raw JSON, or as a values.json attachment. Add flatten: true to bake the result flat.

Limits are deliberate: blank templates only (a PDF that already contains data is refused — attachment contents are never stored or logged, and refusing filled-in forms means this address can't become the thing that forwards someone's data around), 5 MB per PDF, evaluation volume rather than production volume. The full contract is on /fill-by-email.

Make any flat PDF fillable — in the browser

Most PDFs that should be forms aren't — they're flat: text and layout baked into the page, no interactive field layer. Until now, every PDFops surface answered that with "sorry, no AcroForm fields." The new make-fillable tool closes that gap: drop the flat PDF, draw text and checkbox fields where they belong, rename them to something your code will recognize, and download a standard AcroForm PDF that works in Acrobat, Preview, browsers, and every PDF library.

It runs entirely in your browser — rendering (pdf.js) and field creation (pdf-lib) both happen client-side, so the PDF never leaves your machine. On export you also get the ready-to-POST /api/fill-form call with your own field names already in it.

The chain, end to end

Those two pieces compose. Starting from a PDF with no fields at all:

Deterministic fills, and `flatten=true`

Since late July, /api/fill-form and /api/merge are byte-deterministic: the same template and the same values return a byte-identical PDF, every time, across deployments. If you snapshot-test documents in CI or need audit-grade reproducibility, you can now assert on a hash — the how and why is in snapshot-testing PDFs in CI. fill-form also accepts flatten=true, which bakes the filled fields into the page content so the output is no longer editable — re-inspecting a flattened fill reports zero fields.

Also since the last release notes

Try it

The 30-second version, no signup:

curl -X POST https://pdfops.dev/api/fill-form \
  -F "pdf=@your-template.pdf" \
  -F 'fields={"customer_name":"Acme Co","total":"$1,250.00"}' \
  -o filled.pdf

Or skip the terminal entirely: make a PDF fillable, fill it by email, or use the playground. Questions, bugs, or a workflow these primitives don't cover? Tell us — the roadmap is driven by what people actually hit.

Merging PDFs in a Bun server: page order, quota, and the 429 you'll eventually hit

PDFops — Thu, 06 Aug 2026 13:08:28 +0000

Bun ships a fast HTTP server out of the box, so it's a common place to put a small endpoint that stitches a few PDFs together: an application packet, a signed contract plus its exhibits, a statement plus its cover letter. The merge call itself is one request. The part that actually breaks in production is what happens the day a real user's request hits your free-tier ceiling instead of your laptop's IP.

The endpoint

POST /api/merge takes a multipart body with a repeated pdf field and concatenates the inputs in the order the fields appear, not the order the filenames sort in. A Bun server accepting three uploaded files and forwarding them in a fixed order (cover letter, resume, transcript) looks like this:

// server.ts
const PDFOPS_KEY = process.env.PDFOPS_API_KEY;

Bun.serve({
  port: 3000,
  async fetch(req) {
    if (req.method !== "POST" || new URL(req.url).pathname !== "/apply") {
      return new Response("not found", { status: 404 });
    }

    const incoming = await req.formData();
    const cover = incoming.get("cover");
    const resume = incoming.get("resume");
    const transcript = incoming.get("transcript");
    if (!(cover instanceof File) || !(resume instanceof File) || !(transcript instanceof File)) {
      return Response.json({ error: "missing_file" }, { status: 400 });
    }

    // Order matters: pages concatenate in the order these fields are
    // appended, not the order they were uploaded or their filenames.
    const merged = new FormData();
    merged.append("pdf", cover, "cover.pdf");
    merged.append("pdf", resume, "resume.pdf");
    merged.append("pdf", transcript, "transcript.pdf");

    const res = await fetch("https://pdfops.dev/api/merge", {
      method: "POST",
      headers: PDFOPS_KEY ? { "X-API-Key": PDFOPS_KEY } : {},
      body: merged,
    });

    if (!res.ok) {
      const { error, details } = await res.json();
      return Response.json({ error, details }, { status: res.status });
    }

    return new Response(res.body, {
      headers: { "Content-Type": "application/pdf" },
    });
  },
});

Bun's fetch and FormData are the same web standard APIs Node and Deno expose, so this isn't Bun-specific code: it's the pattern any of the three edge-adjacent runtimes use to call PDFops. What's worth pointing at is what the endpoint does after the happy path, because that's the part every one of these worked examples tends to skip.

The 429 you'll eventually hit

Anonymous calls to /api/merge are metered per source IP at 100 requests a month. A Bun server proxying merge requests on behalf of many end users looks like one IP to PDFops, so that ceiling arrives fast: one busy afternoon, not a slow month. When it's exhausted, PDFops returns 429 with a Retry-After header set to the seconds remaining until the 1st of next month UTC, which is not a number worth waiting on inside a live request. The right move is to surface it as a clear, distinct error instead of a generic 500:

if (res.status === 429) {
  const retryAfter = res.headers.get("Retry-After");
  return Response.json(
    {
      error: "merge_quota_exhausted",
      retryAfterSeconds: retryAfter ? Number(retryAfter) : null,
    },
    { status: 503 },
  );
}

A 503 back to your own caller (rather than passing the raw 429 through) is a judgment call worth making deliberately: it tells your client "the service is temporarily unable to complete this," which is closer to the truth than "you personally are rate-limited," since the limit here belongs to your server's IP, not to the end user who just uploaded three files.

Getting past the anonymous cap

A free key raises that ceiling from 100 requests/month per IP to 250 requests/month tied to the key itself, which is the more honest unit for a server proxying requests on behalf of many users. Signing up doesn't require a card:

curl -X POST https://pdfops.dev/api/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

The key arrives by email; set it as PDFOPS_API_KEY in the Bun process's environment and the server code above already picks it up and sends it as X-API-Key. An invalid or revoked key returns 401 invalid_api_key rather than silently falling back to the anonymous IP cap, so a typo in the env var fails loudly instead of quietly eating into a shared quota.

Watching usage before you hit the wall

Waiting for a 429 to find out you're close to the ceiling means your first signal is a broken request in front of a real user. GET /api/usage reads the same counter the rate limiter enforces, so a periodic check against it can warn before the wall instead of after:

const usage = await fetch("https://pdfops.dev/api/usage", {
  headers: { "X-API-Key": PDFOPS_KEY },
}).then((r) => r.json());

// { tier: "free", limit: 250, used: 231, remaining: 19, period: "2026-08", resetsAt: "2026-09-01T00:00:00Z" }
if (usage.remaining < 20) {
  console.warn(`pdfops quota low: ${usage.remaining} of ${usage.limit} left this period`);
}

Run that check on a schedule, a Bun cron job, or just a log line at the top of a handler that fires once an hour, and the upgrade decision happens on your terms, with the usage curve in front of you, instead of during an incident.

What doesn't carry across the merge

Merging preserves every page of every input in the order supplied, but document-level structure doesn't union: AcroForm fields belong to the document, not the individual pages, so a merge of two filled forms doesn't produce one document with both sets of fields intact. If the cover letter or resume above were AcroForm templates that still needed values written in, that has to happen via POST /api/fill-form before the merge call, not after.

Snapshot-testing generated PDFs in CI with a hash instead of a diff

PDFops — Thu, 30 Jul 2026 13:08:17 +0000

A headless-browser renderer stamps a fresh /CreationDate into every PDF it produces, reorders internal objects between runs, and can re-hint fonts slightly differently depending on the machine that ran it. A snapshot test built on "diff these bytes" fails on every single run against that kind of renderer, whether or not the invoice actually changed. PDFops fills the same template and field values into byte-identical output every time, so a hash-based snapshot test can catch what actually changed: the template, or the data, instead of drowning in render noise.

Why a raw PDF diff doesn't work

Open two PDFs produced a minute apart by the same rendering pipeline and run a byte-level diff, and you'll get hits even when the visible content is identical:

None of that is a bug in the renderer. It's just what "render HTML to a page" costs you: the output is a fresh artifact each time, built from a pipeline with several points where non-content bytes can legitimately differ. A snapshot test needs the opposite guarantee: same input, same bytes, always.

What determinism changes

POST /api/fill-form only writes into AcroForm fields that already exist in the template you upload. It doesn't re-render the page, re-flow layout, or touch anything outside the fields you named. Send the same template and the same field values twice and the response bytes match, down to the last one. That's the whole property a snapshot test needs: hash the output once, commit the hash, and every later run either matches it or tells you something real happened: the template changed, the field values changed, or the request itself is wrong.

The workflow

Keep a fixture template and a fixed set of field values in the repo, call fill-form with them, hash the response, and compare against a committed golden hash. This script does the comparing part:

// scripts/verify-pdf-snapshot.mjs
import { createHash } from 'node:crypto';
import { readFile } from 'node:fs/promises';

const GOLDEN_HASH = (await readFile('fixtures/invoice.sha256', 'utf8')).trim();
const FIELDS = { customer_name: 'Acme Co', total: '$1,250.00' };

const template = await readFile('fixtures/invoice-template.pdf');
const form = new FormData();
form.append('pdf', new Blob([template]), 'invoice-template.pdf');
form.append('fields', JSON.stringify(FIELDS));

const res = await fetch('https://pdfops.dev/api/fill-form', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.PDFOPS_API_KEY },
  body: form,
});

if (!res.ok) {
  const { error, details } = await res.json();
  throw new Error(`fill-form failed (${error}): ${details}`);
}

const bytes = new Uint8Array(await res.arrayBuffer());
const hash = createHash('sha256').update(bytes).digest('hex');

if (hash !== GOLDEN_HASH) {
  console.error(`snapshot mismatch\n  got:      ${hash}\n  expected: ${GOLDEN_HASH}`);
  process.exit(1);
}
console.log('PDF snapshot matches.');

Wire it into a pull-request workflow the same way you'd wire up any other check:

# .github/workflows/pdf-snapshot.yml
name: pdf-snapshot
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: node scripts/verify-pdf-snapshot.mjs
        env:
          PDFOPS_API_KEY: ${{ secrets.PDFOPS_API_KEY }}

A pull request that touches the invoice template but leaves the field values alone now fails this job with a clear reason, instead of a green check that never looked.

Updating the golden hash on purpose

When the template changes for real, regenerate the fixture hash and commit it as its own reviewable line, so the person reviewing the pull request sees exactly what triggered it:

node scripts/verify-pdf-snapshot.mjs --update
git diff fixtures/invoice.sha256

A one-line hash change next to a template edit reads as expected. The same one-line hash change with no template edit in the diff is the exact signal a snapshot test exists to raise.

Getting a key for CI

GitHub-hosted runners draw from a shared pool of Azure IP ranges used by many unrelated jobs at once, and PDFops' anonymous trial meters by IP address. A CI job running keyless can share its 100-requests-per-month bucket with other repositories' traffic on the same address, which makes for a confusing rate-limit failure that has nothing to do with your own test volume. POST /api/signup with an email gets a free key delivered to your inbox: 250 requests/month, no card.

curl -X POST https://pdfops.dev/api/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

Store it as a repository secret (PDFOPS_API_KEY in the workflow above) and the job's quota is yours alone to watch, with GET /api/usage available if you want to check it from a script instead of the dashboard.

Migrating off wkhtmltopdf on AWS Lambda

PDFops — Thu, 23 Jul 2026 13:07:58 +0000

wkhtmltopdf's GitHub repo was archived in January 2023, its organization followed in July 2024, and its last release still carries an unpatched, CVSS-9.8 server-side request forgery. None of that has stopped it from running inside a Lambda Layer behind thousands of invoice and receipt endpoints — because "swap out the rendering engine" sounds like a multi-week project. Usually it isn't. If what you're generating is the same layout with different data every time, the fix is smaller than a rendering migration: stop rendering HTML and fill a form instead.

The state of wkhtmltopdf, plainly

Three facts, so you can decide how urgent this is without taking my word for it:

None of this is a knock on the original project — it did its job for over a decade. But "archived + unpatched critical CVE" is the point where a security review stops asking "is this still fine" and starts asking "why is this still here."

Why it's worse specifically on Lambda

wkhtmltopdf isn't a library — it's a compiled binary wrapping a decade-old fork of QtWebKit, which means running it in a function means shipping the binary alongside your code, not importing a package:

When this migration doesn't apply

Be honest about what you're actually rendering before doing this. PDFops fills fields in a PDF template — it doesn't render arbitrary HTML and CSS. If your output genuinely varies in layout — long-form articles, portfolio pages, dashboards with charts, anything where the structure changes per document, not just the values — you still need a real browser renderer. That's a different migration (Puppeteer or Playwright in a proper sandbox, not a Lambda Layer binary), and this guide isn't it.

But check what you're actually generating. Most wkhtmltopdf endpoints render the same HTML template every time — an invoice, a receipt, a monthly statement, a contract — with only the data changing. That's a form problem wearing an HTML renderer's clothes, and it's the case this guide covers.

The swap

Re-author the HTML template once as a real PDF with AcroForm fields — where a Liquid/Handlebars variable used to sit, there's now a named form field. Acrobat's Prepare Form tool, LibreOffice Draw's Form Controls toolbar, or pdftk on an existing PDF all work; it's a one-time job per template, not a per-request cost. Don't have one handy to test against? Grab the sample invoice-template.pdf — it ships with customer_name and total fields already wired up.

Once the template has real fields, POST /api/fill-form replaces the entire render step: upload the template plus a JSON object of field values, get back a filled PDF. No HTML string assembly, no CSS, no rendering engine — just data going into boxes that already exist.

The Lambda handler

Node.js 22.x runtime, ESM, no Layer. The template ships inside the deployment zip and is read once at cold start — outside the handler — so a warm invocation does zero filesystem work before calling the API:

// index.mjs — AWS Lambda (Node.js 22.x), Function URL
import { readFile } from 'node:fs/promises';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { PdfOps, PdfOpsError } from 'pdfops-sdk';

const here = dirname(fileURLToPath(import.meta.url));
// Bundled in the deployment package — no Layer, no /tmp write.
const template = await readFile(join(here, 'invoice-template.pdf'));

const pdfops = new PdfOps({ apiKey: process.env.PDFOPS_API_KEY });

export const handler = async (event) => {
  if (event.requestContext?.http?.method !== 'POST') {
    return { statusCode: 405, body: 'POST a JSON body: { customer_name, total }' };
  }

  const invoice = JSON.parse(event.body ?? '{}');

  try {
    const filled = await pdfops.fillForm(template, {
      customer_name: String(invoice.customer_name ?? ''),
      total: String(invoice.total ?? ''),
    });

    return {
      statusCode: 200,
      headers: { 'content-type': 'application/pdf' },
      body: Buffer.from(filled).toString('base64'),
      isBase64Encoded: true,
    };
  } catch (e) {
    if (e instanceof PdfOpsError) {
      return { statusCode: e.status, body: JSON.stringify({ error: e.code, details: e.message }) };
    }
    throw e;
  }
};

npm install pdfops-sdk, zip index.mjs, node_modules, and invoice-template.pdf together, set PDFOPS_API_KEY as an environment variable, done. Compare that deployment package — a handful of KB of pure JavaScript — to a Lambda Layer carrying a 50-80MB native binary, and the size difference alone is most of why cold starts get faster: there's no subprocess to spin up before your code even runs.

What you get beyond removing the CVE

Filling a form is a narrower operation than rendering HTML, and narrower means more predictable. The same input bytes and the same field values produce byte-identical output every time — no font-substitution drift, no headless-renderer version bump silently reflowing last month's invoices. If that determinism matters for hashing, caching, or diffing PDFs in CI, that's the whole argument in the case for deterministic PDF filling.

Getting a key

The handler above needs a key to run past the anonymous trial. POST /api/signup with an email gets a free one — 250 requests/month, no card, delivered to your inbox (never in the response body, so inbox possession doubles as ownership proof):

curl -X POST https://pdfops.dev/api/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

Anonymous calls (no X-API-Key header) still work at 100 requests/IP/month — enough to run the example below before deciding whether to wire in a key.

Try it

Prove the fill step from a terminal before touching Lambda:

curl -X POST https://pdfops.dev/api/fill-form \
  -F "pdf=@invoice-template.pdf" \
  -F 'fields={"customer_name":"Acme Co","total":"$1,250.00"}' \
  -o filled.pdf

filled.pdf opens with both fields populated — that curl call is exactly what the Lambda handler above does under the hood, just wrapped in the SDK's typed fillForm method instead of raw multipart.

DEV Community: PDFops

Merging a Letter invoice with an A4 attachment in pypdf, and the page size nobody normalizes

What /MediaBox actually is

Reproducing the mismatch

Why a viewer hides it and a rasterizer doesn't

Normalizing to one page size before merging

Try it

Giving an AI agent PDF tools over MCP, and why it has to inspect before it fills

What pdf_inspect gives the agent

Wiring it in

A two-step request, three tool calls

The part that breaks on a hosted server

Try it

Filling a checkbox with pypdf, and the on-state string it never validates

What actually decides whether a box looks checked

Reproducing the silent no-op

Reading the real on-state before you fill

The default that trades one bug for a viewer-dependent one

What that breaks beyond checkboxes

Try it

Packing-slip PDFs from a fulfillment webhook, and the redelivery that duplicates them

The shape of the job

At-least-once means sometimes-twice

A single atomic claim, not two separate steps

The handler

Releasing a claim that never finished

Try it

Filling a PDF from a Python Lambda with no dependencies to package

The shape of the job

Why the standard library is enough here

Building the multipart body by hand

The Lambda handler

Quota, and the shared-IP problem

Try it

Bulk-filling PDFs from a CSV, and the 429 you shouldn't retry

The shape of the job

Check the quota before you start

The script

The 429 that isn't worth retrying

Try it

Automating PDF fills, merges, and invoices in n8n without a Function node

Installing it

The five operations

A worked example: fill from a webhook, catch the typo first

Two more recipes, already built

Keyless works; a key gets you further

Try it

Filling encrypted government PDFs: what actually works, measured

Why a public form rejects your library

The shell answer: pdftk fills them natively

The dump_data_fields trap

The in-process answer: decrypt first

How common is this class?

The forms this does not save

Related

PDFops v0.10: fill a PDF by email, make any PDF fillable

Fill a PDF by email — fill@pdfops.dev

Make any flat PDF fillable — in the browser

The chain, end to end

Deterministic fills, and flatten=true

Also since the last release notes

Try it

Merging PDFs in a Bun server: page order, quota, and the 429 you'll eventually hit

The endpoint

The 429 you'll eventually hit

Getting past the anonymous cap

Watching usage before you hit the wall

What doesn't carry across the merge

Related

Snapshot-testing generated PDFs in CI with a hash instead of a diff

Why a raw PDF diff doesn't work

What determinism changes

The workflow

Updating the golden hash on purpose

Getting a key for CI

Related

Migrating off wkhtmltopdf on AWS Lambda

The state of wkhtmltopdf, plainly

Why it's worse specifically on Lambda

When this migration doesn't apply

Deterministic fills, and `flatten=true`