Core API

Invoice Creator API

Create e-invoices in various formats for 37 countries. Supports XRechnung, ZUGFeRD, Factur-X, FatturaPA and many more.

POST/api/v1/invoice/{countryCode}/{format}/generate

Example: POST /api/v1/invoice/de/xrechnung/generate

Authentication

The API uses Bearer Token authentication. Add your API key in the Authorization header:

bash

1Authorization: Bearer sk_live_abc123...

sk_test_* - Test mode for development — same response, same quota and same rate limit as a live key

sk_live_* - Live mode (production invoices, billed)

Example

bash

1curl -X POST https://service.invoice-api.xhub.io/api/v1/invoice/de/xrechnung/generate \
2  -H "Authorization: Bearer sk_live_abc123..." \
3  -H "Content-Type: application/json" \
4  -d '{
5    "invoice": {
6    "invoiceNumber": "RE-2025-001",
7    "type": "invoice",
8    "issueDate": "2025-01-15",
9    "dueDate": "2025-02-15",
10    "currency": "EUR",
11    "seller": {
12      "name": "Meine Firma GmbH",
13      "street": "Musterstraße 1",
14      "city": "Berlin",
15      "postalCode": "10115",
16      "countryCode": "DE",
17      "taxId": "123/456/78901",
18      "vatId": "DE123456789",
19      "email": "rechnung@meinefirma.de",
20      "phone": "+49 30 1234567",
21      "bankAccount": {
22        "iban": "DE89370400440532013000",
23        "bic": "COBADEFFXXX"
24      }
25    },
26    "buyer": {
27      "name": "Kunde AG",
28      "street": "Kundenweg 42",
29      "city": "München",
30      "postalCode": "80331",
31      "countryCode": "DE",
32      "vatId": "DE987654321",
33      "email": "einkauf@kunde.de"
34    },
35    "countrySpecific": {
36      "countryCode": "DE",
37      "buyerReference": "BUYER-REF-001"
38    },
39    "items": [
40      {
41        "position": 1,
42        "description": "Beratungsleistung",
43        "articleNumber": "CONS-001",
44        "quantity": 10,
45        "unit": "HUR",
46        "unitPrice": 150.00,
47        "taxRate": 19,
48        "taxCategoryCode": "S",
49        "netAmount": 1500.00,
50        "taxAmount": 285.00,
51        "grossAmount": 1785.00
52      }
53    ],
54    "subtotal": 1500.00,
55    "total": 1785.00,
56    "taxSummary": [
57      {
58        "taxRate": 19,
59        "netAmount": 1500.00,
60        "taxAmount": 285.00
61      }
62    ],
63    "paymentTerms": {
64      "dueDays": 30,
65      "description": "Zahlbar innerhalb von 30 Tagen ohne Abzug"
66    },
67    "paymentMethods": [
68      {
69        "type": "bank_transfer",
70        "details": "SEPA-Überweisung"
71      }
72    ],
73    "notes": "Vielen Dank für Ihren Auftrag!"
74    }
75  }'

Response

On success you will receive 200 OK with the created invoice object:

json

1{
2  "success": true,
3  "format": "xrechnung",
4  "filename": "RE-2026-0042.xml",
5  "mimeType": "application/xml",
6  "hash": "9f2c1b7d4e8a03f5c6b9d0e1a2f3c4b5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
7  "payloadHash": "3b1e6c5a9d2f04b7e8c1a0f3d6b9e2c5a8f1d4b7e0c3a6f9d2b5e8c1a4f7d0b3",
8  "data": "PD94bWwgdmVyc2lvbj0iMS4wIj8+...base64encoded...",
9  "errors": [],
10  "complianceErrors": [],
11  "warnings": [
12    {
13      "code": "MISSING_OPTIONAL",
14      "message": "Buyer reference is recommended for public-sector invoices",
15      "field": "countrySpecific.buyerReference"
16    }
17  ]
18}

Response Fields

Field	Type	Description
`success`	boolean	Indicates whether the invoice was successfully created
`format`	string	The generated format, always lowercase (e.g. xrechnung, zugferd, facturx, pdf)
`filename`	string	Suggested filename for the invoice
`mimeType`	string	MIME type of the generated file (e.g. application/xml, application/pdf)
`hash`	string	SHA-256 hash of the generated document
`data`	string	Base64-encoded invoice data
`errors`	array	List of errors (code, message, field)
`warnings`	array	List of warnings (code, message, field)

Request Parameters

Path Parameters

Parameter	Type	Description
`countryCode`required	string	ISO 3166-1 alpha-2 country code, lower case — all 37: `ae, at, au, be, bg, ch, cy, cz, de, dk, ee, es, fi, fr, gb, gr, hr, hu, ie, is, it, jp, li, lt, lu, lv, mt, nl, no, nz, om, pl, pt, ro, se, si, sk`
`format`required	string	Target format — all 15: `ebinterface, facturae, facturx, fatturapa, hr-fisk, isdoc, ksef, mydata, nav, pdf, peppol-ubl, qr-bill, ubl, xrechnung, zugferd`

XRechnung (Germany)

/api/v1/invoice/de/xrechnung/generate

ZUGFeRD (Germany)

/api/v1/invoice/de/zugferd/generate

Factur-X (France)

/api/v1/invoice/fr/facturx/generate

FatturaPA (Italy)

/api/v1/invoice/it/fatturapa/generate

ebInterface (Austria)

/api/v1/invoice/at/ebinterface/generate

PDF (all countries)

/api/v1/invoice/de/pdf/generate

Body Parameters

Parameter	Type	Required	Description
`invoiceNumber`	string		Unique invoice number of the issuer
`type`	string		Document type: invoice \| credit_note \| correction \| proforma \| partial \| partial_construction \| partial_final_construction \| final_construction \| self_billed. Default: invoice. proforma is rejected with a 422 for XRechnung and Peppol BIS.
`issueDate`	string		Invoice date in YYYY-MM-DD format
`dueDate`	string	-	Due date in YYYY-MM-DD format — optional, the spec does not list dueDate in invoice.required
`deliveryDate`	string	-	Delivery or service date in YYYY-MM-DD format
`seller`	object		Seller/invoice issuer (details below)
`buyer`	object		Buyer/invoice recipient (details below)
`items`	array		Invoice line items (at least 1)
`currency`	string		Currency code (ISO 4217). Default: EUR
`subtotal`	number		Net total (automatically calculated if not provided)
`total`	number		Gross total (automatically calculated if not provided)
`taxSummary`	array		Tax summary by tax rates (automatically calculated)
`orderNumber`	string	-	Purchase order reference number
`customerNumber`	string	-	Customer number at the seller
`contractNumber`	string	-	Contract number
`servicePeriod`	object	-	Service period (start, end as ISO 8601 date)
`paymentTerms`	object	-	Payment terms (dueDays, description, earlyPaymentDiscount with days and discountPercent)
`paymentMethods`	array	-	Payment methods (type: bank_transfer\|direct_debit\|credit_card …, details as free text) — for bank_transfer, seller.bankAccount with IBAN must be set
`countrySpecific`	object	-	Country-specific fields — countryCode is required (e.g. "DE"). For DE additionally: buyerReference (BT-10), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer
`notes`	string	-	Free-text note on the invoice
`templateId`	string	-	Reference to a saved PDF template by UUID
`formatOptions.template`	string	-	Inline BlockTemplate JSON for PDF layout
`formatOptions.zugferdProfile`	string	-	ZUGFeRD / Factur-X profile: EN16931, BASIC or EXTENDED. On /generate the key is formatOptions.profile; zugferdProfile is only a legacy alias. MINIMUM and BASIC WL are rejected with a 400.

seller (Seller)

Parameter	Type	Required	Description
`name`	string		Company name
`tradingName`	string	-	Trading name (if different from legal name)
`street`	string		Street and house number
`additionalStreet`	string	-	Additional address line
`city`	string		City
`postalCode`	string		Postal code
`state`	string	-	State/region (ISO 3166-2)
`countryCode`	string		Country code (ISO 3166-1 alpha-2)
`taxId`	string	-	Tax ID
`vatId`	string	-	VAT ID (e.g. DE123456789)
`email`	string	-	Email address
`phone`	string	-	Phone number
`website`	string	-	Website URL
`bankAccount`	object	-	Bank account (iban, bic, bankName, accountHolder) — required as soon as paymentMethods contains a credit transfer (EN 16931, BR-61)

buyer (Buyer)

Parameter	Type	Required	Description
`name`	string		Company name
`tradingName`	string	-	Trading name (if different from legal name)
`street`	string		Street and house number
`additionalStreet`	string	-	Additional address line
`city`	string		City
`postalCode`	string		Postal code
`state`	string	-	State/region (ISO 3166-2)
`countryCode`	string		Country code (ISO 3166-1 alpha-2)
`taxId`	string	-	Buyer tax ID
`vatId`	string	-	Buyer VAT ID
`email`	string	-	Email address
`phone`	string	-	Phone number
`website`	string	-	Website URL
`bankAccount`	object	-	Bank account (iban, bic, bankName, accountHolder) — required as soon as paymentMethods contains a credit transfer (EN 16931, BR-61)

items[] (Line Items)

Parameter	Type	Required	Description
`position`	number		Position number (automatically assigned if not provided)
`description`	string		Line item description
`articleNumber`	string	-	Article number
`quantity`	number		Quantity
`unit`	string		Unit (UN/ECE Rec 20). Default: C62 (piece)
`unitPrice`	number		Unit price net
`taxRate`	number		VAT rate in percent (e.g. 19, 7, 0)
`taxCategoryCode`	string	-	Tax category code (e.g. "S" for standard, "Z" for 0%, "E" for exempt)
`netAmount`	number		Net amount (calculated if not provided)
`taxAmount`	number		Tax amount (calculated if not provided)
`grossAmount`	number		Gross amount (calculated if not provided)

paymentTerms (Payment Terms)

Parameter	Type	Required	Description
`dueDays`	number	-	Payment term in days (required)
`description`	string	-	Free-text description of payment terms
`earlyPaymentDiscount`	object	-	Early-payment discount: { days, discountPercent }

37 supported countries and their formats

Use these combinations of countryCode and format in the endpoint path.

DEGermany

PDFZUGFeRD 2.3/2.4/2.5XRechnung 3.0/3.0.2 *

ATAustria

PDFebInterface *UBL (Peppol BIS 3.0)

CHSwitzerland

PDFZUGFeRD (CH)QR-Bill *

FRFrance

PDFFactur-X 1.0/1.08/1.09 *UBL (Peppol BIS 3.0)

ITItaly

PDFFatturaPA 1.2.3 *

ESSpain

PDFFacturae *UBL (Peppol BIS 3.0)

NLNetherlands

PDFUBL (Peppol BIS 3.0 / NL-CIUS)

BEBelgium

PDFUBL (Peppol BIS 3.0)Factur-X

PLPoland

PDFKSeF FA(3) (national UBL slot) *UBL (Peppol BIS 3.0)

PTPortugal

PDFCIUS-PT (national UBL) *UBL (Peppol BIS 3.0)

AEUnited Arab Emirates

PDFUBL (PINT-AE)

AUAustralia

PDFUBL (PINT AU-NZ)

BGBulgaria

PDFUBL (Peppol BIS 3.0)

CYCyprus

PDFUBL (Peppol BIS 3.0)

CZCzech Republic

PDFISDOC *UBL (Peppol BIS 3.0)

DKDenmark

PDFUBL (Peppol BIS 3.0)

EEEstonia

PDFUBL (Peppol BIS 3.0)

FIFinland

PDFUBL (Peppol BIS 3.0)

GBUnited Kingdom

PDFUBL (Peppol BIS 3.0 / UK)

GRGreece

PDFmyDATA *

HRCroatia

PDFUBL (Peppol BIS 3.0)

HUHungary

PDFNAV *

IEIreland

PDFUBL (Peppol BIS 3.0)

ISIceland

PDFUBL (Peppol BIS 3.0)

JPJapan

PDFUBL (PINT-JP)

LILiechtenstein

PDFQR-BillUBL (Peppol BIS 3.0)

LTLithuania

PDFUBL (Peppol BIS 3.0)

LULuxembourg

PDFUBL (Peppol BIS 3.0)

LVLatvia

PDFUBL (Peppol BIS 3.0)

MTMalta

PDFUBL (Peppol BIS 3.0)

NONorway

PDFUBL (Peppol BIS 3.0)

NZNew Zealand

PDFUBL (PINT AU-NZ)

OMOman

PDFUBL (PINT-OM)

RORomania

PDFeFactura (CIUS-RO) *UBL (Peppol BIS 3.0)

SESweden

PDFUBL (Peppol BIS 3.0)

SISlovenia

PDFUBL (Peppol BIS 3.0)

SKSlovakia

PDFUBL (Peppol BIS 3.0)

* Recommended format for the country | = Available

Leitweg-ID for Public Authorities (Germany)

For XRechnung invoices to public authorities (agencies, municipalities, etc.), the Leitweg-ID is mandatory. The format is: XXX-XXXXX-XX

You receive the Leitweg-ID from the contracting authority. A list of all Leitweg-IDs can be found in the official directory.

Limits

The number of invoice line items in items[] is capped per plan. The cap applies when generating, on both validate routes and when converting — not when parsing.

Plan	Line items per invoice
Free	25
Starter	100
Premium	1,000
Enterprise	individually agreed

The API always rejects more than 15,000 line items per invoice. That is the service's technical ceiling, and only an Enterprise contract reaches it.

Response above the cap

Above the cap the API answers with HTTP 400 and the error code TOO_MANY_LINE_ITEMS. The response names the counted number and the limit; no invoice is produced and the call is not billed.

json

1{
2  "error": "TOO_MANY_LINE_ITEMS",
3  "message": "Too many line items for this plan",
4  "lineItems": {
5    "count": 128,
6    "limit": 100
7  }
8}

Which plan carries which cap: Pricing and line items per plan

Error Codes

HTTP	Code	Description	Solution
400	`INVALID_REQUEST`	Invalid request data	Check JSON format and required fields
400	`VALIDATION_FAILED`	E-invoice does not match the schema	Check error messages in errors array
400	`UNSUPPORTED_FORMAT`	Format not supported for this country	Check supported formats for the selected country
400	`TOO_MANY_LINE_ITEMS`	The invoice has more line items than the plan allows	Read lineItems.count and lineItems.limit, split the document or change plan — see Limits
401	`UNAUTHORIZED`	Missing or invalid API key	Check the Authorization header (sk_test_* or sk_live_*)
403	`FORBIDDEN`	Missing required entitlement	Check the Authorization header (sk_test_* or sk_live_*)
422	`INVALID_VAT_ID`	Invalid VAT ID	Check the format (e.g. DE + 9 digits)
422	`INVALID_COUNTRY`	Invalid country code	Use a supported ISO 3166-1 alpha-2 code
429	`QUOTA_EXCEEDED`	Quota exhausted	Upgrade your plan or wait until next month
500	`INTERNAL_ERROR`	Internal Server Error	Retry the request or contact support

Full error list: Error Handling Documentation

Further Documentation

Field reference

Every field of the invoice object with type and required flag

Validator API

Validate invoices

Converter API

Convert formats

Webhooks

Receive events

Playground

Test API interactively