POST /api/invoice

This is the first PDFops endpoint that ships its own template: /api/fill-form fills an AcroForm PDF you bring; /api/invoice draws the whole document from data. That makes it a natural fit for a Stripe webhook that turns a payment into an invoice PDF, a monthly billing cron, or freelancer tooling — see the Stripe walkthrough and the invoices use case.

Request

Method: POST. URL: https://pdfops.dev/api/invoice. Body: application/json.

Each entry in items:

Successful (2xx) calls count 1 request against your quota — the same meter as the other PDF endpoints. Check consumption with GET /api/usage.

Full request example

{
  "from": { "name": "Acme Studio LLC", "lines": ["100 Main St", "Portland, OR 97201"] },
  "to": "Globex Corporation",
  "invoice_number": "INV-0042",
  "date": "2026-07-21",
  "due": "2026-08-20",
  "currency": "USD",
  "tax_rate": 8.5,
  "items": [
    { "description": "Design retainer — July", "quantity": 1, "unit_price": 2400 },
    { "description": "Landing page build", "quantity": 3, "unit_price": 650 }
  ],
  "notes": "Payment by bank transfer within 30 days."
}

Response

On success: 200 OK, Content-Type: application/pdf — a complete US-Letter invoice:

• Header with the invoice number, date, and due date.
• FROM and BILL TO blocks (name plus up to 6 address lines each).
• Items table with per-line amounts — long invoices auto-paginate past one page.
• Subtotal, tax (when tax_rate is set), and total, formatted in the invoice currency.
• The notes block, when provided.

On any failure: 4xx, Content-Type: application/json, body is { "error": "<code>", "details": "<explanation>" }.

Deterministic output

The same JSON body returns a byte-identical PDF — every time. The PDF's internal metadata dates are pinned to the invoice date rather than the render time, so nothing in the file varies between runs. Hash the output today, render the same JSON tomorrow, get the same hash.

Practically, that means re-rendering is idempotent and safe: a Stripe webhook that retries, a monthly cron that re-runs, or a "regenerate" button that fires twice all produce the same file — dedup, caching, content-addressed storage, and audit diffs just work. There is no wall-clock input at all: the PDF's metadata dates are pinned to your date when given, and to a fixed epoch otherwise — never to render time — so a body that omits date is still byte-stable across days (it just has no date line on the document).

Branding

Anonymous calls and Free-tier keys produce PDFs with a small "Generated with pdfops.dev" footer line. Indie and Pro keys produce clean output with no branding — see /pricing.

Error codes

Example — curl

curl -X POST https://pdfops.dev/api/invoice \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pdfops_live_..." \
  -d '{
    "from": "Acme Studio LLC",
    "to": "Globex Corporation",
    "invoice_number": "INV-0042",
    "date": "2026-07-21",
    "items": [
      { "description": "Design retainer — July", "unit_price": 2400 }
    ]
  }' \
  -o invoice-INV-0042.pdf

The X-API-Key header is optional — drop it to use the anonymous quota (the PDF then carries the footer line).

Example — JavaScript: Stripe webhook → invoice PDF

The marquee pattern from the Stripe walkthrough: a Worker receives an invoice.paid event and renders the PDF. Because output is deterministic, Stripe's webhook retries re-produce the identical file — store it keyed by hash or invoice number and duplicates collapse for free.

export default {
  async fetch(req, env) {
    const event = await req.json(); // Stripe webhook — verify the signature first
    const inv = event.data.object;  // an invoice.paid Invoice object

    const res = await fetch('https://pdfops.dev/api/invoice', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': env.PDFOPS_KEY,
      },
      body: JSON.stringify({
        from: { name: 'Acme Studio LLC', lines: ['100 Main St', 'Portland, OR 97201'] },
        to: inv.customer_name,
        invoice_number: inv.number,
        date: new Date(inv.created * 1000).toISOString().slice(0, 10),
        currency: inv.currency.toUpperCase(),
        items: inv.lines.data.map((line) => ({
          description: line.description,
          quantity: line.quantity,
          unit_price: line.amount / 100 / line.quantity,
        })),
      }),
    });

    const pdf = await res.arrayBuffer();
    await env.BUCKET.put(`invoices/${inv.number}.pdf`, pdf); // R2, email it, etc.
    return new Response('ok');
  },
};

FAQ

← All docs · PDFops home