E-invoicing API: one JSON invoice, every EU format

01What an e-invoice is

For years an emailed PDF was a perfectly good invoice. The buyer read it, typed the numbers into their accounting system and paid. EU law now calls that a paper-like format. An electronic invoice in the legal sense is a file in a structured format that follows the European standard EN 16931.

There are two ways to deliver that structure. The first is the XML on its own, which is what XRechnung is. The second is a hybrid: a normal PDF that people read, with the same invoice attached inside it as XML. ZUGFeRD in Germany and Factur-X in France are the hybrid formats, and since ZUGFeRD 2.1 they are technically the same file.

In a hybrid invoice the XML is the part that counts legally. The German tax authority says so explicitly. That is why the numbers on the page and in the XML must never differ, and why CastPDF builds both from one calculation.

02ZUGFeRD, XRechnung or Factur-X?

The usual question is ZUGFeRD vs XRechnung. Public authorities in Germany expect XRechnung, usually through a portal, and tell you whether they take CII or UBL. Businesses mostly prefer ZUGFeRD, because their staff can still open and read the PDF. Both count as e-invoices under the German rules. Our ZUGFeRD page and XRechnung page go deeper into each one.

Profiles: how much data the XML carries

Use en16931 unless your customer asks for something else. It carries the whole invoice, and it is what most receiving software expects. The two smallest profiles carry no lines, so the German rules do not accept them as invoices.

03The German e-invoicing mandate, 2025 to 2028

The rules come from the Growth Opportunities Act (Wachstumschancengesetz) and the Federal Ministry of Finance letters that explain it. Invoices to consumers are out of scope, and so are small invoices up to EUR 250 and travel tickets. The ministry’s FAQ has the details in German.

• XRechnung counts as an e-invoice.
• ZUGFeRD from version 2.0.1 counts, except the MINIMUM and BASIC WL profiles.
• A plain PDF is no longer an e-invoice, even if you send it by email.
• In a hybrid ZUGFeRD file, the XML wins if it differs from the page.

Public buyers are a separate, older story. Suppliers to the federal administration have had to send e-invoices since November 2020, and XRechnung is the format those buyers expect. Several federal states have similar rules. Each public buyer gives you a Leitweg-ID, which goes into the invoice as the buyer reference.

04E-invoicing in France: Factur-X and the 2026 reform

France chose a different model from Germany. Invoices between French businesses will travel through approved platforms (plateformes agréées), which also report the data to the tax administration. The French finance laws set two dates, and the first one has already passed.

The platforms accept three base formats: Factur-X, CII and UBL. Factur-X is the popular one, because it stays a readable PDF. CastPDF makes the Factur-X file; your approved platform carries it to the buyer and reports it. CastPDF is not a platform and does not transmit invoices. Ask your platform which Factur-X profile it wants, and check the current dates with it, because French deadlines have moved before.

Our Factur-X page shows a French invoice request and the fields French invoices need.

05One request, from JSON to e-invoice

Put the invoice in e_invoice on the normal POST /v1/pdf request. You need no template: the built-in invoice template renders the page. Change standard to switch formats; the invoice stays the same.

{
  "e_invoice": {
    "standard": "zugferd",
    "profile": "en16931",
    "invoice": {
      "number": "RE-2026-0815",
      "issue_date": "2026-10-10",
      "currency": "EUR",
      "seller": {
        "name": "Lindqvist Software GmbH",
        "vat_id": "DE123456789",
        "address": { "line1": "Kastanienallee 12", "city": "Berlin", "postal_code": "10435", "country_code": "DE" }
      },
      "buyer": {
        "name": "Brightwater Kaffee GmbH",
        "address": { "city": "Hamburg", "postal_code": "20457", "country_code": "DE" }
      },
      "payment": { "iban": "DE89370400440532013000", "due_date": "2026-11-09" },
      "lines": [
        { "name": "Software licence", "quantity": 1, "unit_price": "4800.00", "vat": { "category": "S", "rate": 19 } },
        { "name": "Printed handbook", "quantity": 3, "unit_price": "24.90", "vat": { "category": "S", "rate": 7 } }
      ]
    }
  }
}

curl https://api.castpdf.com/v1/pdf \
  -H "Authorization: Bearer $CASTPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-RE-2026-0815" \
  -d @RE-2026-0815.json \
  -o RE-2026-0815.pdf

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

const body = await readFile('RE-2026-0815.json', 'utf8');
const res = await fetch('https://api.castpdf.com/v1/pdf', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CASTPDF_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'invoice-RE-2026-0815',
  },
  body,
});
if (!res.ok) {
  const { error } = await res.json();
  // invalid_e_invoice lists every problem in error.details.issues
  throw new Error(`${error.code}: ${error.message}`);
}
await writeFile('RE-2026-0815.pdf', Buffer.from(await res.arrayBuffer()));

import json
import os

import requests

with open("RE-2026-0815.json", encoding="utf-8") as f:
    body = json.load(f)

res = requests.post(
    "https://api.castpdf.com/v1/pdf",
    headers={
        "Authorization": f"Bearer {os.environ['CASTPDF_API_KEY']}",
        "Idempotency-Key": "invoice-RE-2026-0815",
    },
    json=body,
    timeout=60,
)
if not res.ok:
    error = res.json()["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
with open("RE-2026-0815.pdf", "wb") as f:
    f.write(res.content)

HTTP/1.1 200 OK
content-type: application/pdf
content-disposition: attachment; filename="RE-2026-0815.pdf"
x-e-invoice: zugferd/en16931
x-pages: 1

Change standard to xrechnung-ubl and the same request returns the XRechnung XML instead, once the invoice has the extra XRechnung fields. The API reference lists every field, and the ZUGFeRD and XRechnung guide covers credit notes, reverse charge and exempt sales.

06Totals computed once, printed twice

• Each line is quantity times net price, rounded to cents, then line discounts and charges.
• VAT is computed once per category and rate, not per line, and rounded half away from zero.
• Exact decimals throughout: no floating point, so 0.1 plus 0.2 is 0.30.
• Send your own totals if you like; any field that differs is reported with our value.
• Reverse charge, intra-EU supplies and exports get the standard exemption text and code.

Many billing systems round VAT on every line. EN 16931 rounds it once per rate, which can differ by a cent. If you send your totals, the API tells you exactly which one is off and why, before anything is rendered or counted.

07What we validated, and how

The samples cover six invoice shapes: two VAT rates with discounts and charges, reverse charge, an exempt sale, a credit note, an intra-EU supply and a 40-line rounding test. They also cover logos, test watermarks and right-to-left and Chinese text in the PDF.

08Check or create an e-invoice for free

Two free tools use the same engine as the API, without an account. The e-invoice validator reads an XRechnung XML or a ZUGFeRD or Factur-X PDF and checks the fields and the totals. The e-invoice generator turns a short form into a ZUGFeRD PDF or an XRechnung XML.

Both are rate limited and stamp a small CastPDF footer on generated PDFs. When you need e-invoices from your own system, the API does the same work without the footer on paid plans.

09What an e-invoice costs

An e-invoice counts on your plan exactly like any other PDF. The Free plan includes 100 documents a month, and paid plans start at $19 a month for 2,500. Test keys make unlimited watermarked e-invoices while you build, and a request that fails validation is never counted. See pricing for every plan.

10Common questions

11Everything on the E-invoicing API

Every guide, template and example that builds on this page. Each one answers a narrower question in more depth.