The e_invoice field

e_invoice on POST /v1/pdf turns one structured invoice into an EU e-invoice: a Factur-X or ZUGFeRD PDF (a PDF/A-3b with the XML inside) or an XRechnung XML. The visible PDF and the XML come from the same data and the same totals, so they cannot disagree. This page is the field reference; the e-invoicing guide walks through a first invoice step by step, and the e-invoicing overview explains the formats and the German and French rules.

Each e-invoice request makes one document and is counted like any other PDF; a rejected invoice is never counted. Field names follow EN 16931, the European standard behind all three formats; the business term (BT) or group (BG) is given for each field so you can map your own data.

The request

{
  "e_invoice": {
    "standard": "factur-x",
    "profile": "en16931",
    "invoice": {
      "number": "RE-2026-0815",
      "issue_date": "2026-10-10",
      "currency": "EUR",
      "seller": {
        "name": "Muster Software GmbH",
        "vat_id": "DE123456789",
        "address": { "line1": "Hauptstrasse 1", "city": "Berlin", "postal_code": "10115", "country_code": "DE" },
        "electronic_address": { "value": "[email protected]" },
        "contact": { "name": "Billing team", "phone": "+49 30 1234567", "email": "[email protected]" }
      },
      "buyer": {
        "name": "Example Customer AG",
        "address": { "line1": "Marktplatz 5", "city": "Hamburg", "postal_code": "20095", "country_code": "DE" },
        "electronic_address": { "value": "[email protected]" }
      },
      "payment": { "iban": "DE89370400440532013000", "due_date": "2026-10-24" },
      "lines": [
        { "name": "Consulting", "quantity": 40, "unit_code": "HUR", "unit_price": "120.00", "vat": { "category": "S", "rate": 19 } },
        { "name": "Handbook", "quantity": 3, "unit_price": "24.90", "vat": { "category": "S", "rate": 7 } }
      ]
    }
  },
  "response": "url"
}

This request is valid as it stands: the totals come to 4,874.70 net, 917.23 VAT and 5,791.93 due. Without template_id and html, the built-in invoice template renders it.

The other fields of POST /v1/pdf work as usual: response, filename, metadata, async, test, the page options and deliver (except with an XRechnung). Templates: without template_id and html, the built-in invoice template renders the invoice. With your own template_id (or html), the template receives the invoice as template data with every amount already computed: seller, customer, invoice, payment, items (each with net_amount), totals, vat_breakdown, doc_allowances, doc_charges, and e_invoice with the standard, profile and a label such as "Factur-X EN 16931". Send data only if you want to replace that data.

Amounts, quantities, prices and rates are JSON numbers or decimal strings such as "24.90"; strings avoid any doubt about decimals. Dates are YYYY-MM-DD. Text fields are trimmed and may be at most 1,000 characters unless noted.

The invoice

Parties and addresses

A party (seller, buyer):

An invoice with VAT must show the seller's vat_id or tax_number. A seller without either, on an invoice without VAT, needs legal_registration_id or id instead.

An address has country_code (ISO 3166-1 alpha-2, such as DE; required) and optionally line1, line2, line3, city, postal_code and subdivision (a region or state).

Lines

VAT categories

vat.category is a UNTDID 5305 code, and rate a percent: 19 means 19 %.

Payment

All fields are optional, but when an amount is due you must send due_date or terms (from the basic-wl profile up).

Allowances and charges

Document level allowances and charges lower or raise the whole invoice:

Totals

We compute every total with exact decimals and the EN 16931 rules. Each line is quantity times net price (divided by the price base quantity), rounded to cents, minus its allowances plus its charges. VAT is computed once per category and rate on the taxable amount, rounded half away from zero, not per line.

totals is optional. If you send it, every field you send must match ours, or the request fails with invalid_e_invoice naming the field, our value and yours. The fields are line_total (BT-106), allowance_total (BT-107), charge_total (BT-108), tax_basis_total (BT-109), tax_total (BT-110), grand_total (BT-112), prepaid (BT-113), rounding (BT-114) and due_payable (BT-115). Sending them is a good way to catch a rounding difference between your system and the invoice before anyone receives it.

Tax exemptions

tax_exemptions maps a VAT category to { "reason", "code" }: the exemption reason in words (BT-120) and its VATEX code (BT-121), for example { "E": { "reason": "Exempt under Article 132 of Directive 2006/112/EC", "code": "VATEX-EU-132-1A" } }.

• E (exempt) requires a reason or a code.
• AE, K, G and O get the standard text and code by default (for example "Reverse charge" with VATEX-EU-AE); send your own to replace them.
• S, Z, L and M have no exemption reason, so an entry for them is an error.

XRechnung requirements

XRechnung, the format German public buyers require, needs more than EN 16931:

• buyer_reference: the Leitweg-ID for public buyers;
• a seller contact with name, phone (at least three digits) and email;
• city and postal_code in the seller's and the buyer's address;
• an electronic_address for the seller and the buyer (for public buyers usually the Leitweg-ID with scheme 0204);
• payment (at least means_code, and the iban for a transfer), and the seller's vat_id or tax_number.

The API lists whatever is missing, all at once.

What comes back

• Factur-X and ZUGFeRD return a PDF, like any other request, with factur-x.xml embedded (xrechnung.xml for the ZUGFeRD xrechnung profile). ZUGFeRD 2.1 and later and Factur-X use the same file name and the same XML.
• XRechnung returns application/xml, named after the invoice number (RE-2026-0815.xml) unless you send a filename.
• A binary response carries x-e-invoice: standard/profile, such as factur-x/en16931. A url response adds "e_invoice": { "standard", "profile", "xml_filename" }. The stored file, at its signed link, keeps its content type.

"e_invoice": { "standard": "factur-x", "profile": "en16931", "xml_filename": "factur-x.xml" }

Errors

An invalid invoice is a 400 with the code invalid_e_invoice, before anything is rendered or counted, also for async: true. details.issues lists up to 50 problems as { "path", "message" } (paths start at e_invoice), and details.more_issues counts the rest. This is the real answer for the request above sent as xrechnung-cii with a wrong totals.tax_total:

{
  "error": {
    "code": "invalid_e_invoice",
    "message": "The e-invoice has 2 problems. The first: e_invoice.invoice.buyer_reference: is required for XRechnung: the buyer reference, which for German public buyers is the Leitweg-ID (for example 04011000-12345-67).",
    "docs_url": "https://castpdf.com/docs/errors#invalid_e_invoice",
    "details": {
      "issues": [
        { "path": "e_invoice.invoice.buyer_reference", "message": "is required for XRechnung: the buyer reference, which for German public buyers is the Leitweg-ID (for example 04011000-12345-67)." },
        { "path": "e_invoice.invoice.totals.tax_total", "message": "is 917.24, but it should be 917.23 (the VAT of each rate rounded to cents (19% of 4800.00 = 912.00; 7% of 74.70 = 5.23)). EN 16931 rounds each line to cents and the VAT once per rate, not per line." }
      ]
    }
  }
}

An unknown standard or profile value, or an e_invoice without invoice, is an invalid_request (400) from the request check instead; a known profile that the standard does not offer (such as factur-x with xrechnung) is an invalid_e_invoice. To check an XML you already have, use the free e-invoice validator.

Limits

• deliver cannot be combined with an XRechnung (invalid_request): download the XML with response: "url" and send it yourself.
• Batches do not accept e_invoice yet.
• An invoice has 1 to 2,000 lines, inside the usual request limit of 5 MB.
• Test keys watermark the PDF as usual and never watermark the XML; a test document is still not counted.

What was validated

In our test suite every generated XML passes the official XSD and Schematron rules (CEN EN 16931 1.3.16, Factur-X 1.09 and KoSIT XRechnung 3.0.2). On 2026-10-10, veraPDF 1.30.3 found 16 of 16 sample PDFs compliant with PDF/A-3b, and the KoSIT validator 1.6.3 accepted all 14 EN 16931 and XRechnung sample files. The ZUGFeRD, Factur-X and XRechnung guide explains the formats in depth.