Generate Invoice

POST /v1/generate

Generate ZUGFeRD 2.3 / Factur-X / XRechnung / Peppol / UBL compliant invoices from structured JSON data.

On This Page

→ Request Body Parameters → Supported Formats (9 types) → Invoice Object Fields → Address Object (seller/buyer) → Line Item Object → Payment Object → Example Request → Response Format

Request Body

Parameter Type Required Description
format string No auto (default), zugferd, facturx, xrechnung, etc. See Supported Formats
template string No minimal (default), classic, or compact
locale string No en, de, fr, es, it (auto-detects if omitted)
invoice object Yes Invoice data with fields documented below
customization object No PDF customization: logo_base64, logo_width_mm, footer_text

Supported Formats

The API supports 9 invoice formats for different regions and use cases. Use the format parameter to specify the output format.

auto
Auto-Detection (default)

Automatically selects best format based on country codes. Germany → ZUGFeRD, France → Factur-X, etc.

zugferd
ZUGFeRD 2.3 (PDF/A-3 + CII XML)

German e-invoicing standard. PDF/A-3 with embedded UN/CEFACT CII XML. Profile: EN 16931.

facturx
Factur-X 1.0 (PDF/A-3 + CII XML)

French equivalent of ZUGFeRD. Same technical structure, different branding. Profile: EN 16931.

xrechnung
XRechnung 3.0 (PDF/A-3 + UBL XML)

German B2G standard (required for government invoices). PDF/A-3 with embedded UBL 2.1 XML.

peppol
Peppol BIS Billing 3.0 (XML only)

Pan-European Public Procurement Online. UBL-based XML for cross-border e-procurement (EU, UK, AU, SG, NZ).

ubl
UBL 2.1 Invoice (XML only)

OASIS Universal Business Language. Widely used international XML standard for e-invoicing.

cii
UN/CEFACT CII (XML only)

Cross Industry Invoice. UN/CEFACT XML standard, basis for ZUGFeRD/Factur-X.

fatturapa
FatturaPA 1.2.1 (XML only)

Italian electronic invoicing format (required for SDI - Sistema di Interscambio).

pdf
Plain PDF (PDF only, no XML)

Human-readable PDF invoice without embedded structured data. Not compliant with e-invoicing regulations.

Invoice Object

The invoice object contains all invoice data according to EN 16931. Fields marked as required are mandatory for ZUGFeRD/Factur-X compliance.

Field Type Required EN 16931 Description
number string Yes BT-1 Invoice number (e.g., "2026-001")
date string Yes BT-2 Invoice date (ISO 8601: YYYY-MM-DD)
due_date string No BT-9 Due date (ISO 8601: YYYY-MM-DD)
type_code string No BT-3 Invoice type: 380 (Invoice, default), 381 (Credit Note), 384 (Corrected Invoice)
currency string No BT-5 ISO 4217 code (default: EUR)
buyer_reference string No* BT-10 Buyer reference / Purchase Order Number (required for B2G)
seller object Yes BG-4 Seller/supplier address
buyer object Yes BG-7 Buyer/customer address
items array Yes BG-25 Line items (min. 1)
payment object No BG-16 Payment information
note string No BT-22 Free-text invoice note

EN 16931 Reference: The EN 16931 column shows the Business Term (BT) or Business Group (BG) identifier from the European e-invoicing standard. Learn more about EN 16931

Address Object (seller/buyer)

Address objects are used for both seller (BG-4) and buyer (BG-7) information. The seller's VAT ID is strongly recommended for tax compliance.

Field Type Required EN 16931 Description
name string Yes BT-27/BT-44 Legal name of the party
trading_name string No BT-28/BT-45 Trading name (if different from legal name)
street string No BT-35/BT-50 Street name and house number
additional_line string No BT-36/BT-51 Additional address line
city string No BT-37/BT-52 City name
postal_code string No BT-38/BT-53 Postal/ZIP code
country string No BT-40/BT-55 ISO 3166-1 alpha-2 code (default: DE)
vat_id string No* BT-31/BT-48 VAT identification number (e.g., DE123456789)
tax_number string No BT-32 Seller tax registration number (seller only)
email string No BT-43/BT-58 Contact email address
phone string No BT-42/BT-57 Contact phone number

Note: For B2B invoices within the EU, the seller's vat_id is required for VAT reverse charge. For B2G invoices, additional fields like buyer_reference may be mandatory.

Line Item Object

Each invoice must contain at least one line item (BG-25). Line items represent the goods or services being invoiced.

Field Type Required EN 16931 Description
description string Yes BT-153 Item name/description
quantity number Yes BT-129 Invoiced quantity (e.g., 8)
unit string No BT-130 UN/ECE Rec 20 code (default: C62). See Units Reference
unit_price number Yes BT-146 Net price per unit (e.g., 120.00)
vat_rate number No BT-152 VAT rate percentage (default: 19)
vat_category string No BT-151 VAT category: S (Standard), Z (Zero-rated), E (Exempt), K (Intra-community), G (Export)
seller_id string No BT-155 Seller's item identifier (SKU)
buyer_id string No BT-156 Buyer's item identifier
global_id string No BT-157 Global trade item number (GTIN/EAN)

Payment Object

Payment information (BG-16) for the invoice. While optional, providing bank details improves payment processing.

Field Type Required EN 16931 Description
means_code string No BT-81 Payment means code: 30 (Credit transfer), 58 (SEPA), 59 (SEPA Direct Debit)
iban string No BT-84 Payment account IBAN
bic string No BT-86 Payment service provider BIC/SWIFT
account_name string No BT-85 Payment account name
reference string No BT-83 Remittance information / payment reference
terms string No BT-20 Payment terms text (e.g., "Payment within 14 days")

Example Request

{
  "format": "zugferd",
  "template": "minimal",
  "locale": "de",
  "invoice": {
    "number": "2026-001",
    "date": "2026-01-15",
    "due_date": "2026-01-29",
    "seller": {
      "name": "Acme GmbH",
      "street": "Musterstraße 1",
      "city": "Berlin",
      "postal_code": "10115",
      "country": "DE",
      "vat_id": "DE123456789",
      "email": "rechnung@acme.de"
    },
    "buyer": {
      "name": "Customer AG",
      "street": "Kundenweg 42",
      "city": "München",
      "postal_code": "80331",
      "country": "DE"
    },
    "items": [
      {
        "description": "Software Development",
        "quantity": 40,
        "unit": "HUR",
        "unit_price": 120.00,
        "vat_rate": 19
      },
      {
        "description": "Project Management",
        "quantity": 8,
        "unit": "HUR",
        "unit_price": 95.00,
        "vat_rate": 19
      }
    ],
    "payment": {
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "terms": "Payment within 14 days"
    }
  },
  "customization": {
    "logo_base64": "data:image/png;base64,iVBORw0KGgoAAAANSU...",
    "logo_width_mm": 35,
    "footer_text": "CEO: John Doe | HRB 12345 | District Court Berlin"
  }
}

Response

{
  "pdf_base64": "JVBERi0xLjcKJeLjz9MKNSAwIG9...",
  "filename": "rechnung-2026-001.pdf",
  "validation": {
    "status": "valid",
    "profile": "EN16931",
    "version": "2.3"
  },
  "account": {
    "remaining": 459,
    "plan": "starter"
  }
}