stripe-xrechnung

Stripe Invoice JSON → XRechnung 3.0.2 UBL 2.1, offline. Python ≥ 3.11. Dependencies: pydantic and lxml. No Stripe API calls, no Peppol access point, no network.

Search terms this library exists for: stripe xrechnung, Stripe Invoice to EN 16931 / XRechnung UBL.

Scope

This repo is the mapper: Stripe Invoice JSON (or an invoice.finalized Event wrapper) → XRechnung 3.0.2 UBL 2.1 XML.

Out of scope here: ZUGFeRD / Factur-X CII, PDF/A-3, Peppol, the official KoSIT Java validator, LemonSqueezy, receive/archive.

Disclaimer

Not tax advice. Not legal advice. You fill legal identity fields. This library never invents a USt-IdNr (VAT ID). Empty seller VAT stays empty; local validation then reports BR-DE-16 if a VAT category requires BT-31/BT-32. Local checks are structural + VAT math + a selected BR-DE subset. They are not the official KoSIT validator.

Kleinunternehmer remain exempt from issuing structured e-invoices under the current German mandate; receiving is not exempt (since 1 Jan 2025). This library will not pretend a Kleinunternehmer must issue XRechnung.

Install

git clone https://github.com/catmia/stripe-xrechnung.git
cd stripe-xrechnung
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
stripe-xrechnung doctor

90-second demo

stripe-xrechnung emit fixtures/stripe_invoice.finalized.json -o /tmp/xrechnung.xml

Stripe does not ship seller VAT id or IBAN. Put them in a top-level seller object on the Invoice JSON, or pass --seller seller.json. The library refuses to invent a USt-IdNr.

CLI

FILE may be - (stdin). A Stripe Event wrapper (invoice.finalized) is unwrapped automatically.

Python API:

from stripe_xrechnung import map_stripe, emit_ubl, validate_invoice
import json

payload = json.loads(open("invoice.json", encoding="utf-8").read())
invoice = map_stripe(payload)           # CanonicalInvoice
xml = emit_ubl(invoice)                 # bytes, UBL 2.1
report = validate_invoice(invoice)      # not KoSIT

How Stripe Invoice JSON is mapped

Stripe amounts are integer cents. Dates are Unix seconds unless already ISO. Seller legal identity is not on a Stripe Invoice — overlay it. Never invent a USt-IdNr.

Seller overlay (--seller or top-level seller):

{
  "name": "Beispiel GmbH",
  "street": "Musterstraße 1",
  "city": "Berlin",
  "postal_code": "10115",
  "country": "DE",
  "vat_id": "DE123456789",
  "email": "rechnung@beispiel.example",
  "phone": "+49-30-000000-0",
  "contact_name": "Ina Beispiel",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX"
}

The vat_id above is a textbook example, not a live id. Put your id. Fixtures use Beispiel GmbH, textbook VAT ids, and IBANs labelled EXAMPLE.

What Stripe will never give you: seller USt-IdNr, Steuernummer, IBAN, Leitweg-ID, VAT categories K/AE/G with VATEX codes, Kleinunternehmer status. Those are master data.

KoSIT goldens

Included UBL goldens golden/xrechnung_b2b_19.xml and golden/xrechnung_b2g_leitweg.xml were run through KoSIT Validator 1.6.3 with the XRechnung 3.0.2 configuration (bundle 2026-01-31) on 2026-08-31 and assessed ACCEPTABLE (valid="true"). Pytest asserts emit output byte-equals those goldens. That is a pin of this library's synthetic fixtures, not a certificate that your invoices are valid. Run the official KoSIT validator on your data before sending.

License

MIT — see LICENSE. Commercial use of generated invoices is OK. The library does not claim copyright in your invoice data.

Field-level Stripe → BT-* notes (same mapping this library implements): https://dev.to/thor_4e886628f33fca7fa8df/stripe-invoice-json-en-16931-bt-germany-2026-cda

A fuller CLI (ZUGFeRD / Factur-X CII, archive, German error catalog) lives at https://vegasweiss.gumroad.com/l/e-rechnung-kit-2026