Zum Inhalt springen
Referenz

Feldreferenz

Jedes Feld des invoice-Objekts, das die Creator- und Validator-API entgegennehmen. Diese Seite wird aus der OpenAPI-Spezifikation erzeugt und kann deshalb nicht von ihr abweichen.

263
Felder
10
Pflichtfelder auf invoice
39
Objekte

Erzeugt aus Invoice.xhub API · POST /api/v1/invoice/{countryCode}/{format}/generate

Ein vollständiges Beispiel

Dieselben Daten, die im Playground auf der Startseite vorbelegt sind — vollständig, mit allen Pflichtfeldern.

json
1{
2 "invoice": {
3 "invoiceNumber": "RE-2025-001",
4 "type": "invoice",
5 "issueDate": "2025-01-15",
6 "dueDate": "2025-02-15",
7 "currency": "EUR",
8 "seller": {
9 "name": "Muster GmbH",
10 "vatId": "DE811128135",
11 "street": "Musterstraße 1",
12 "postalCode": "10115",
13 "city": "Berlin",
14 "countryCode": "DE",
15 "email": "info@muster.de",
16 "phone": "+49 30 12345678",
17 "bankAccount": {
18 "iban": "DE89370400440532013000",
19 "bic": "COBADEFFXXX"
20 }
21 },
22 "buyer": {
23 "name": "Beispiel AG",
24 "vatId": "DE136695976",
25 "street": "Beispielweg 42",
26 "postalCode": "80331",
27 "city": "München",
28 "countryCode": "DE"
29 },
30 "items": [
31 {
32 "position": 1,
33 "description": "Beratungsleistung",
34 "quantity": 10,
35 "unit": "HUR",
36 "unitPrice": 150,
37 "taxRate": 19,
38 "netAmount": 1500,
39 "taxAmount": 285,
40 "grossAmount": 1785
41 }
42 ],
43 "taxSummary": [
44 {
45 "taxRate": 19,
46 "netAmount": 1500,
47 "taxAmount": 285
48 }
49 ],
50 "subtotal": 1500,
51 "total": 1785,
52 "paymentTerms": {
53 "dueDays": 30,
54 "description": "Zahlbar innerhalb von 30 Tagen"
55 },
56 "countrySpecific": {
57 "countryCode": "DE",
58 "leitwegId": "991-12345-67"
59 }
60 }
61}

Drei Stellen, an denen Integrationen hängenbleiben

Sobald paymentMethods eine Überweisung enthält, verlangt EN 16931 (BR-61) die Zahlungskonto-Kennung. Ohne seller.bankAccount.iban wird die Rechnung abgelehnt.

Die Mengeneinheit ist ein Code nach UN/ECE Rec 20, kein Klartext: C62 (Stück), HUR (Stunde), KGM (Kilogramm), MTR (Meter), DAY (Tag). "Stk" oder "piece" fällt bei BR-CL-23 durch.

Wird countrySpecific gesetzt, ist countryCode darin Pflicht — auch wenn der Ländercode bereits im Pfad steht.

Alle Felder

invoice

Invoice data to generate document from

FeldTypPflichtBeschreibung
invoiceNumberstringPflichtfeldUnique invoice number
Beispiel: INV-2026-0042
typestringPflichtfeldInvoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where PEPPOL-EN16931-P0112 restricts both 326 (partial) and 384 (correction) to a DE seller together with a DE buyer), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently, and never a silent 381: `correction` on a non-DE-to-DE Peppol route always falls back to 380, not to the credit-note code. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).
Erlaubte Werte: invoice, credit_note, proforma, correction, partial, partial_construction, partial_final_construction, final_construction, self_billed
issueDatestringPflichtfeldIssue date (ISO 8601: YYYY-MM-DD)
Beispiel: 2026-03-20
dueDatestringoptionalDue date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.
Beispiel: 2026-04-19
deliveryDatestringoptionalDelivery/service date (ISO 8601)
Beispiel: 2026-03-20
servicePeriodobjectoptionalService period (Leistungszeitraum, BG-14). Required in DE if different from issueDate. Send `start`, `end` or both (BR-CO-19); an empty object returns a 400. Formats whose schema requires both dates (ebInterface, Facturae) return a 400 `INVOICE_SERVICE_PERIOD_BOTH_DATES_REQUIRED` when one is missing; ISDOC has no invoicing period and reports `INVOICE_SERVICE_PERIOD_NOT_REPRESENTABLE` as a warning.
sellerobjectPflichtfeldSeller party information
buyerobjectPflichtfeldBuyer party information
payeeobjectoptionalPayee (BG-10), if different from the seller. On the CH/LI QR bill (`qr-bill`) the payee is the creditor: postal code, city, country and its own bank account are required.
itemsobject[]PflichtfeldInvoice line items. Hard ceiling: 5000, or 25000 where large-invoice validation is enabled (`maxItems` shows the value of the server you call). Routes that render a PDF layout stay at 5000 — `/generate` for `pdf` or a hybrid format such as ZUGFeRD or Factur-X, and `/convert` into a hybrid format; above that they answer 400 with the same `too_big` body (`maximum: 5000`). To embed the XML of a larger invoice into your own PDF, use `/embed`. Your plan may allow fewer — a request above the plan limit is rejected with 400 `TOO_MANY_LINE_ITEMS`. Sub-items (`subItems`) count as lines: above 25000 lines in total the request is rejected with 400 `TOO_MANY_INVOICE_LINES`; above 5000 lines in total on a server without large-invoice validation the response carries the warning `INVOICE_LINES_ABOVE_MODE_LIMIT`.
currencystringPflichtfeldCurrency code (ISO 4217, three upper-case letters). A code outside ISO 4217 is rejected under `/api/v2` with 400 `INVALID_CURRENCY` (`field: currency`); under `/api/v1` the request is processed as before and `warnings` carries `CURRENCY_CODE_UNKNOWN`.
Beispiel: EUR
subtotalnumberPflichtfeldTotal net amount
Beispiel: 4800
totalnumberPflichtfeldTotal gross amount
Beispiel: 5712
taxSummaryobject[]PflichtfeldTax summary per tax rate
paymentTermsobjectoptionalPayment terms
cashDiscountPercentnumberoptionalCash discount (Skonto) percentage agreed on the document. > 0, <= 100, at most two decimals. On German e-invoices this becomes the #SKONTO#TAGE=n#PROZENT=n.nn# line inside the payment terms note (BR-DE-18). Ignored when paymentTerms.earlyPaymentDiscount is present.
Beispiel: 2
cashDiscountDaysintegeroptionalDays within which the cash discount applies (integer, 0..365).
Beispiel: 14
cashDiscountBaseAmountnumberoptionalOptional base amount for the cash discount when it is not the payable amount (BASISBETRAG segment, BR-DE-18).
Beispiel: 9500
paymentMethodsobject[]optionalPayment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.
orderNumberstringoptionalPurchase order number (Bestellnummer)
Beispiel: PO-2026-0815
customerNumberstringoptionalCustomer number at the seller
Beispiel: KD-42
contractNumberstringoptionalContract number (BT-12)
Beispiel: V-2025-1234
projectNumberstringoptionalProject reference (BT-11). More than 100 characters: warning `FIELD_TOO_LONG` (field `projectNumber`), the value is written unchanged; a later release rejects it with 400.
Beispiel: PROJ-2026-42
tenderReferencestringoptionalTender or lot reference (BT-17). Several public contracting authorities reject an invoice without it. Rendered as `cac:OriginatorDocumentReference`.
Beispiel: VgV-2026-042
objectIdstringoptionalObject identifier of the invoice (BT-18) — the thing the invoice is about, e.g. a contract object or a plant. Rendered as `cac:AdditionalDocumentReference` with `cbc:DocumentTypeCode` 130.
Beispiel: PROJ-7
objectIdSchemestringoptionalScheme of the object identifier (BT-18-1, UNTDID 1153).
Beispiel: AAJ
businessProcessstringoptionalBusiness process type (BT-23). Rendered as `cbc:ProfileID`. When omitted the generator emits the profile the target format prescribes.
Beispiel: urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
roundingAmountnumberoptionalRounding amount (BT-114)
Beispiel: 0.01
prepaidAmountnumberoptionalAmount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.
Beispiel: 500
allowancesChargesobject[]optionalInvoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.
deliveryobjectoptionalDelivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).
directDebitMandateobjectoptionalDirect debit mandate (BG-19). Send it with direct_debit: most formats (XRechnung, Peppol PEPPOL-EN16931-R061) require the mandate reference for payment means code 49 and 59.
cardAccountobjectoptionalCard payment details (BG-18). Set it together with a card payment means code (BT-81 = 48, 54 or 55). Formats that cannot represent the group report a GROUP_NOT_REPRESENTABLE warning instead of dropping it silently.
supportingDocumentsobject[]optionalReferences to supporting documents WITHOUT the file (BT-122/BT-123) — for the file itself use `attachments`. Oman needs the registryId here for the prepayment document and for exports with VATZR-OM-12.
retentionobjectoptionalSecurity retention. Reduces only the payment, never the totals or the VAT. Written as a sentence into the payment terms (BT-20 or the national equivalent) of every e-invoice format that has payment terms, in the language of the seller (machine-translated for FR, NL, IT, ES, PL; English for other languages). A reason you send is used as given and is not translated. Do not use allowancesCharges for it. Formats or profiles without payment terms (ZUGFeRD and Factur-X MINIMUM, and myDATA without a payment method) reject the request with 422 (RETENTION_NOT_CARRIED); a plain PDF is not affected.
prepaymentsobject[]optionalThe individual prepayments behind `prepaidAmount` (BT-113). Needed where a country requires the prepayment invoice to be referenced — Oman writes each one as `cac:AdditionalDocumentReference` with document type code PDR. Elsewhere `prepaidAmount` alone is enough.
notesstringoptionalAdditional notes displayed on the invoice
Beispiel: Vielen Dank für Ihren Auftrag!
profilestringoptionalXRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.
Erlaubte Werte: xrechnung, xrechnung-extension
referencedInvoiceNumberstringoptionalNumber of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.
Beispiel: INV-2026-0040
referencedInvoiceDatestringoptionalIssue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.
Beispiel: 2026-03-15
deliveryNoteobjectoptionalDespatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.
thirdPartyPaymentsobject[]optionalThird-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.
attachmentsobject[]optionalEmbedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL. More than 20 attachments: warning `FIELD_TOO_LONG` (field `attachments`); a later release rejects it with 400.
serviceCategorystringoptionalService category hint for the reverse-charge note. When a line or the VAT breakdown uses `taxCategoryCode: "AE"`, the generator writes the mandatory note: with seller and buyer in the same country and `construction`, the national note (in Germany §13b UStG); otherwise the EU-wide note (Art. 226 No. 11a VAT Directive), where one exists for the seller country. Without the buyer's country the response carries `REVERSE_CHARGE_BUYER_COUNTRY_MISSING`.
Erlaubte Werte: construction, general
constructionTaxobjectoptionalGerman construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.
countrySpecificobjectoptionalCountry-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.

servicePeriod

Service period (Leistungszeitraum, BG-14). Required in DE if different from issueDate. Send `start`, `end` or both (BR-CO-19); an empty object returns a 400. Formats whose schema requires both dates (ebInterface, Facturae) return a 400 `INVOICE_SERVICE_PERIOD_BOTH_DATES_REQUIRED` when one is missing; ISDOC has no invoicing period and reports `INVOICE_SERVICE_PERIOD_NOT_REPRESENTABLE` as a warning.

FeldTypPflichtBeschreibung
startstringoptionalPeriod start (BT-73, ISO 8601: YYYY-MM-DD)
Beispiel: 2026-03-01
endstringoptionalPeriod end (BT-74, ISO 8601: YYYY-MM-DD)
Beispiel: 2026-03-31

seller

Seller party information

FeldTypPflichtBeschreibung
namestringPflichtfeldLegal name of the party
Beispiel: Muster GmbH
tradingNamestringoptionalTrading name (if different from legal name)
Beispiel: Muster Shop
streetstringoptionalStreet address. More than 200 characters: warning `FIELD_TOO_LONG` (field e.g. `seller.street`), the value is written unchanged; a later release rejects it with 400.
Beispiel: Hauptstraße 42
additionalStreetstringoptionalAdditional address line (BT-36 seller / BT-51 buyer / BT-65 tax representative). More than 200 characters: warning `FIELD_TOO_LONG` (field e.g. `seller.additionalStreet`), the value is written unchanged; a later release rejects it with 400.
Beispiel: 2. OG, Raum 5
addressLine3stringoptionalThird address line (BT-162 seller / BT-163 buyer / BT-164 tax representative).
Beispiel: Gebaeude C
citystringoptionalCity. More than 100 characters: warning `FIELD_TOO_LONG` (field e.g. `seller.city`), the value is written unchanged; a later release rejects it with 400.
Beispiel: Berlin
postalCodestringoptionalPostal code. More than 20 characters: warning `FIELD_TOO_LONG` (field e.g. `seller.postalCode`), the value is written unchanged; a later release rejects it with 400.
Beispiel: 10115
countryCodestringPflichtfeldCountry code (ISO 3166-1 alpha-2)
Beispiel: DE
statestringoptionalState/region (ISO 3166-2). More than 100 characters: warning `FIELD_TOO_LONG` (field e.g. `seller.state`), the value is written unchanged; a later release rejects it with 400.
Beispiel: BE
taxIdstringoptionalNational tax identification number. For the buyer, not transmitted in ZUGFeRD/Factur-X (only the VAT ID is); a warning is returned.
Beispiel: 27/123/45678
vatIdstringoptionalVAT identification number with its country prefix (BT-31 seller / BT-48 buyer / BT-63 tax representative). EN 16931 (BR-CO-09) requires the prefix (ISO 3166-1 alpha-2, Greece `EL`). If the rulebook of the format reports BR-CO-09 and the value starts with a digit, the prefix of the party `countryCode` is added and the response carries the warning `VAT_ID_COUNTRY_PREFIX_ADDED` (field e.g. `buyer.vatId`). Formats without BR-CO-09 keep the value as sent.
Beispiel: DE136695976
registrationNumberstringoptionalPublic register identifier of the party (BT-30 seller / BT-47 buyer) — Handelsregister, Firmenbuch, Companies House, … Rendered as `cac:PartyLegalEntity/cbc:CompanyID`. GENERIC field: until now every country read this from its own country-specific field (AT `tradeRegisterNumber`, FI `yTunnus`, …), so a business without a matching country block could not send its register number at all. Those fields keep working as a fallback.
Beispiel: HRB 12345
registrationSchemestringoptionalISO 6523 ICD code of the register (BT-30-1 / BT-47-1). 🔴 Only set this when the pinned ICD list actually carries a code for the register. The Austrian Firmenbuch has none — an invented code is FATAL per BR-CL-11.
Beispiel: 0198
identifiersobject[]optionalFurther party identifiers (BT-29 seller / BT-46 buyer / BT-60 payee), repeatable. Written by every EN 16931 format. UBL: `cac:PartyIdentification/cbc:ID` (with `schemeID` if set). CII (ZUGFeRD, Factur-X, XRechnung CII, …): entries with `schemeId` become `ram:GlobalID`, entries without become `ram:ID`. Seller: every entry is BT-29. Buyer: BT-46 occurs at most once. The first entry of `buyer.identifiers` is BT-46 and replaces the invoice `customerNumber`; `customerNumber` is then not written and the response carries the warning `FIELD_NOT_WRITTEN` (field `customerNumber`). Without buyer identifiers `customerNumber` stays BT-46. Further buyer entries are not written either (`FIELD_NOT_WRITTEN`, field `buyer.identifiers.<n>`). `vatId` is only BT-31 (`SpecifiedTaxRegistration`, scheme `VA`). One exception, XRechnung (DE), seller: if the seller has no `identifiers`, no legal registration (BT-30) and no written BT-31, BR-CO-26 still needs one of them. Then `vatId` (or else `taxId`) is written as BT-29, and the response carries the warning `SELLER_IDENTIFIER_DERIVED`. Payee: only the first non-empty entry of `payee.identifiers` becomes BT-60 (with its `schemeId`); further entries are not written (`FIELD_NOT_WRITTEN`, field `payee.identifiers.<n>`). Only without one does the payee `vatId` or `taxId` fill BT-60.
emailstringoptionalEmail address
Beispiel: billing@muster.de
phonestringoptionalPhone number
Beispiel: +49 30 12345678
websitestringoptionalWebsite URL
Beispiel: https://muster.de
contactobjectoptionalStructured contact person (BG-6 for seller, BG-9 for buyer)
bankAccountobjectoptionalBank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.
Sobald paymentMethods eine Überweisung enthält, verlangt EN 16931 (BR-61) die Zahlungskonto-Kennung. Ohne seller.bankAccount.iban wird die Rechnung abgelehnt.

seller.identifiers[]

Party identifier with optional scheme (BT-29 / BT-46)

FeldTypPflichtBeschreibung
idstringPflichtfeldIdentifier of the party (BT-29 seller / BT-46 buyer).
Beispiel: 4012345000009
schemeIdstringoptionalIdentification scheme of the identifier (BT-29-1 / BT-46-1, ISO 6523 ICD).
Beispiel: 0088

seller.contact

Structured contact person (BG-6 for seller, BG-9 for buyer)

FeldTypPflichtBeschreibung
namestringoptionalContact person name
Beispiel: Max Mustermann
phonestringoptionalContact phone number
Beispiel: +49 30 12345678
emailstringoptionalContact email address
Beispiel: max@muster.de
departmentstringoptionalDepartment of the contact person (BT-41-0 seller / BT-56-0 buyer). In ZUGFeRD/Factur-X only one of name or department is transmitted; if both are set, the name is used and a warning is returned.
Beispiel: Kreditorenbuchhaltung

seller.bankAccount

Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.

FeldTypPflichtBeschreibung
ibanstringPflichtfeldIBAN (International Bank Account Number)
Beispiel: DE89370400440532013000
bicstringoptionalBIC/SWIFT code (8 or 11 characters)
Beispiel: COBADEFFXXX
bankNamestringoptionalName of the bank
Beispiel: Commerzbank
accountHolderstringoptionalAccount holder name (if different from party name)
Beispiel: TechCorp GmbH

buyer

Buyer party information

FeldTypPflichtBeschreibung
namestringPflichtfeldLegal name of the party
Beispiel: Muster GmbH
tradingNamestringoptionalTrading name (if different from legal name)
Beispiel: Muster Shop
streetstringoptionalStreet address. More than 200 characters: warning `FIELD_TOO_LONG` (field e.g. `seller.street`), the value is written unchanged; a later release rejects it with 400.
Beispiel: Hauptstraße 42
additionalStreetstringoptionalAdditional address line (BT-36 seller / BT-51 buyer / BT-65 tax representative). More than 200 characters: warning `FIELD_TOO_LONG` (field e.g. `seller.additionalStreet`), the value is written unchanged; a later release rejects it with 400.
Beispiel: 2. OG, Raum 5
addressLine3stringoptionalThird address line (BT-162 seller / BT-163 buyer / BT-164 tax representative).
Beispiel: Gebaeude C
citystringoptionalCity. More than 100 characters: warning `FIELD_TOO_LONG` (field e.g. `seller.city`), the value is written unchanged; a later release rejects it with 400.
Beispiel: Berlin
postalCodestringoptionalPostal code. More than 20 characters: warning `FIELD_TOO_LONG` (field e.g. `seller.postalCode`), the value is written unchanged; a later release rejects it with 400.
Beispiel: 10115
countryCodestringPflichtfeldCountry code (ISO 3166-1 alpha-2)
Beispiel: DE
statestringoptionalState/region (ISO 3166-2). More than 100 characters: warning `FIELD_TOO_LONG` (field e.g. `seller.state`), the value is written unchanged; a later release rejects it with 400.
Beispiel: BE
taxIdstringoptionalNational tax identification number. For the buyer, not transmitted in ZUGFeRD/Factur-X (only the VAT ID is); a warning is returned.
Beispiel: 27/123/45678
vatIdstringoptionalVAT identification number with its country prefix (BT-31 seller / BT-48 buyer / BT-63 tax representative). EN 16931 (BR-CO-09) requires the prefix (ISO 3166-1 alpha-2, Greece `EL`). If the rulebook of the format reports BR-CO-09 and the value starts with a digit, the prefix of the party `countryCode` is added and the response carries the warning `VAT_ID_COUNTRY_PREFIX_ADDED` (field e.g. `buyer.vatId`). Formats without BR-CO-09 keep the value as sent.
Beispiel: DE136695976
registrationNumberstringoptionalPublic register identifier of the party (BT-30 seller / BT-47 buyer) — Handelsregister, Firmenbuch, Companies House, … Rendered as `cac:PartyLegalEntity/cbc:CompanyID`. GENERIC field: until now every country read this from its own country-specific field (AT `tradeRegisterNumber`, FI `yTunnus`, …), so a business without a matching country block could not send its register number at all. Those fields keep working as a fallback.
Beispiel: HRB 12345
registrationSchemestringoptionalISO 6523 ICD code of the register (BT-30-1 / BT-47-1). 🔴 Only set this when the pinned ICD list actually carries a code for the register. The Austrian Firmenbuch has none — an invented code is FATAL per BR-CL-11.
Beispiel: 0198
identifiersobject[]optionalFurther party identifiers (BT-29 seller / BT-46 buyer / BT-60 payee), repeatable. Written by every EN 16931 format. UBL: `cac:PartyIdentification/cbc:ID` (with `schemeID` if set). CII (ZUGFeRD, Factur-X, XRechnung CII, …): entries with `schemeId` become `ram:GlobalID`, entries without become `ram:ID`. Seller: every entry is BT-29. Buyer: BT-46 occurs at most once. The first entry of `buyer.identifiers` is BT-46 and replaces the invoice `customerNumber`; `customerNumber` is then not written and the response carries the warning `FIELD_NOT_WRITTEN` (field `customerNumber`). Without buyer identifiers `customerNumber` stays BT-46. Further buyer entries are not written either (`FIELD_NOT_WRITTEN`, field `buyer.identifiers.<n>`). `vatId` is only BT-31 (`SpecifiedTaxRegistration`, scheme `VA`). One exception, XRechnung (DE), seller: if the seller has no `identifiers`, no legal registration (BT-30) and no written BT-31, BR-CO-26 still needs one of them. Then `vatId` (or else `taxId`) is written as BT-29, and the response carries the warning `SELLER_IDENTIFIER_DERIVED`. Payee: only the first non-empty entry of `payee.identifiers` becomes BT-60 (with its `schemeId`); further entries are not written (`FIELD_NOT_WRITTEN`, field `payee.identifiers.<n>`). Only without one does the payee `vatId` or `taxId` fill BT-60.
emailstringoptionalEmail address
Beispiel: billing@muster.de
phonestringoptionalPhone number
Beispiel: +49 30 12345678
websitestringoptionalWebsite URL
Beispiel: https://muster.de
contactobjectoptionalStructured contact person (BG-6 for seller, BG-9 for buyer)
bankAccountobjectoptionalBank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.
Sobald paymentMethods eine Überweisung enthält, verlangt EN 16931 (BR-61) die Zahlungskonto-Kennung. Ohne seller.bankAccount.iban wird die Rechnung abgelehnt.
taxableRecipientbooleanoptionalWhether the buyer is a taxable person. Optional. Evaluated for Portugal only. If you leave it out, the API asks for the full buyer as before.

buyer.identifiers[]

Party identifier with optional scheme (BT-29 / BT-46)

FeldTypPflichtBeschreibung
idstringPflichtfeldIdentifier of the party (BT-29 seller / BT-46 buyer).
Beispiel: 4012345000009
schemeIdstringoptionalIdentification scheme of the identifier (BT-29-1 / BT-46-1, ISO 6523 ICD).
Beispiel: 0088

buyer.contact

Structured contact person (BG-6 for seller, BG-9 for buyer)

FeldTypPflichtBeschreibung
namestringoptionalContact person name
Beispiel: Max Mustermann
phonestringoptionalContact phone number
Beispiel: +49 30 12345678
emailstringoptionalContact email address
Beispiel: max@muster.de
departmentstringoptionalDepartment of the contact person (BT-41-0 seller / BT-56-0 buyer). In ZUGFeRD/Factur-X only one of name or department is transmitted; if both are set, the name is used and a warning is returned.
Beispiel: Kreditorenbuchhaltung

buyer.bankAccount

Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.

FeldTypPflichtBeschreibung
ibanstringPflichtfeldIBAN (International Bank Account Number)
Beispiel: DE89370400440532013000
bicstringoptionalBIC/SWIFT code (8 or 11 characters)
Beispiel: COBADEFFXXX
bankNamestringoptionalName of the bank
Beispiel: Commerzbank
accountHolderstringoptionalAccount holder name (if different from party name)
Beispiel: TechCorp GmbH

payee

Payee (BG-10), if different from the seller. On the CH/LI QR bill (`qr-bill`) the payee is the creditor: postal code, city, country and its own bank account are required.

FeldTypPflichtBeschreibung
namestringoptionalPayee name (BT-59). Required by BR-17 when a payee is given.
Beispiel: Factoring AG
tradingNamestringoptionalTrading name (if different from legal name)
Beispiel: Muster Shop
streetstringoptionalStreet address of the payee
additionalStreetstringoptionalAdditional address line of the payee
addressLine3stringoptionalThird address line (BT-162 seller / BT-163 buyer / BT-164 tax representative).
Beispiel: Gebaeude C
citystringoptionalCity of the payee. Required on the CH/LI QR bill (`qr-bill`): without it 422 `CH_ADDR_005`, field `payee.city`.
postalCodestringoptionalPostal code of the payee. Required on the CH/LI QR bill (`qr-bill`): without it 422 `CH_ADDR_004`, field `payee.postalCode`.
countryCodestringoptionalCountry code of the payee (ISO 3166-1 alpha-2). Required on the CH/LI QR bill (`qr-bill`): without it 422 `CH_ADDR_006`, field `payee.countryCode`.
statestringoptionalState/region (ISO 3166-2). More than 100 characters: warning `FIELD_TOO_LONG` (field e.g. `seller.state`), the value is written unchanged; a later release rejects it with 400.
Beispiel: BE
taxIdstringoptionalNational tax identification number. For the buyer, not transmitted in ZUGFeRD/Factur-X (only the VAT ID is); a warning is returned.
Beispiel: 27/123/45678
vatIdstringoptionalVAT identification number with its country prefix (BT-31 seller / BT-48 buyer / BT-63 tax representative). EN 16931 (BR-CO-09) requires the prefix (ISO 3166-1 alpha-2, Greece `EL`). If the rulebook of the format reports BR-CO-09 and the value starts with a digit, the prefix of the party `countryCode` is added and the response carries the warning `VAT_ID_COUNTRY_PREFIX_ADDED` (field e.g. `buyer.vatId`). Formats without BR-CO-09 keep the value as sent.
Beispiel: DE136695976
registrationNumberstringoptionalPublic register identifier of the payee (BT-61), for example a Handelsregister or Companies House number. Rendered as `cac:PartyLegalEntity/cbc:CompanyID` (UBL) and `ram:SpecifiedLegalOrganization/ram:ID` (CII).
Beispiel: HRB 12345
registrationSchemestringoptionalISO 6523 ICD code of the register (BT-30-1 / BT-47-1). 🔴 Only set this when the pinned ICD list actually carries a code for the register. The Austrian Firmenbuch has none — an invented code is FATAL per BR-CL-11.
Beispiel: 0198
identifiersobject[]optionalPayee identifiers (BT-60). Only the first non-empty entry is written; further entries give `FIELD_NOT_WRITTEN` (field `payee.identifiers.<n>`).
emailstringoptionalEmail address
Beispiel: billing@muster.de
phonestringoptionalPhone number
Beispiel: +49 30 12345678
websitestringoptionalWebsite URL
Beispiel: https://muster.de
contactobjectoptionalStructured contact person (BG-6 for seller, BG-9 for buyer)
bankAccountobjectoptionalThe payee's own account. When set, it is the payment account (BT-84) in every format and the account of the QR bill, instead of `seller.bankAccount`. On the CH/LI QR bill (`qr-bill`) the payee is always the creditor, and creditor and account must match (SIX IG 4.3.1): a payee without its own account gets 422 `CH_IBAN_003`, field `payee.bankAccount.iban`.

payee.identifiers[]

FeldTypPflichtBeschreibung
idstringoptionalIdentifier of the payee (BT-60). Empty entries are skipped.
Beispiel: 4012345000009
schemeIdstringoptionalIdentification scheme of the identifier (BT-29-1 / BT-46-1, ISO 6523 ICD).
Beispiel: 0088

payee.contact

Structured contact person (BG-6 for seller, BG-9 for buyer)

FeldTypPflichtBeschreibung
namestringoptionalContact person name
Beispiel: Max Mustermann
phonestringoptionalContact phone number
Beispiel: +49 30 12345678
emailstringoptionalContact email address
Beispiel: max@muster.de
departmentstringoptionalDepartment of the contact person (BT-41-0 seller / BT-56-0 buyer). In ZUGFeRD/Factur-X only one of name or department is transmitted; if both are set, the name is used and a warning is returned.
Beispiel: Kreditorenbuchhaltung

payee.bankAccount

The payee's own account. When set, it is the payment account (BT-84) in every format and the account of the QR bill, instead of `seller.bankAccount`. On the CH/LI QR bill (`qr-bill`) the payee is always the creditor, and creditor and account must match (SIX IG 4.3.1): a payee without its own account gets 422 `CH_IBAN_003`, field `payee.bankAccount.iban`.

FeldTypPflichtBeschreibung
ibanstringPflichtfeldIBAN (International Bank Account Number)
Beispiel: DE89370400440532013000
bicstringoptionalBIC/SWIFT code (8 or 11 characters)
Beispiel: COBADEFFXXX
bankNamestringoptionalName of the bank
Beispiel: Commerzbank
accountHolderstringoptionalAccount holder name (if different from party name)
Beispiel: TechCorp GmbH

items[]

FeldTypPflichtBeschreibung
positionintegeroptionalLine item position number (BT-126 — zero-indexed line IDs are valid)
Beispiel: 1
descriptionstringPflichtfeldItem description
Beispiel: Software Development Services — March 2026
articleNumberstringoptionalArticle/SKU number — the SELLER's item identifier (BT-155).
Beispiel: SVC-DEV-001
gtinstringoptionalGlobal Trade Item Number (BT-157). Rendered as `cac:StandardItemIdentification/cbc:ID` with `schemeID="0160"`.
Beispiel: 04012345678901
itemDescriptionstringoptionalLonger item description (BT-154), IN ADDITION to `description` (BT-153, the item name). Not a duplicate: the name identifies the article, this describes it. When omitted, the generators repeat the name.
Beispiel: Beratung zur Einfuehrung der E-Rechnung, inkl. Schulung.
buyerItemIdstringoptionalItem identifier assigned by the BUYER (BT-156). Lets the recipient book the line against his own item master without parsing the description text.
Beispiel: KD-ART-9911
classificationobject[]optionalItem classifications (BT-158), repeatable — e.g. UNSPSC, eCl@ss, eTIM.
originCountrystringoptionalCountry of origin of the item (BT-159, ISO 3166-1 alpha-2).
Beispiel: CN
attributesobject[]optionalItem attributes (BG-32), repeatable — name and value, both required.
notestringoptionalFree-text note for THIS line (BT-127).
Beispiel: Leistung erbracht am 12. und 13. Maerz, Nachweis anbei.
objectIdstringoptionalObject identifier of the line (BT-128) — e.g. a meter number or a ticket id. Rendered as `cac:DocumentReference` with `cbc:DocumentTypeCode` 130.
Beispiel: ZAEHLER-4711
objectIdSchemestringoptionalScheme of the object identifier (BT-128-1, UNTDID 1153).
Beispiel: AAJ
orderLineReferencestringoptionalReferenced purchase order line number (BT-132).
Beispiel: 5
buyerAccountingReferencestringoptionalBuyer's accounting reference / cost centre for this line (BT-133).
Beispiel: KST-4711
servicePeriodobjectoptionalService period of THIS line (BG-26, BT-134/135). A collective invoice spanning several months needs the period per line — on document level it would be wrong.
quantitynumberPflichtfeldQuantity (BT-129). Written to the XML with the decimals you send — at least two, at most what the target format allows (FatturaPA and TicketBAI 8, NAV 10, CIUS-PT 3). Negative values allowed for return/credit lines, EN 16931 BG-25. More decimals than the format allows are rounded to its limit, and `warnings` carries `QUANTITY_DECIMALS_ROUNDED` (`lossy: true`) with the field and the written value.
Beispiel: 40
unitstringPflichtfeldUnit code (UN/ECE Rec 20)
Beispiel: HUR
Die Mengeneinheit ist ein Code nach UN/ECE Rec 20, kein Klartext: C62 (Stück), HUR (Stunde), KGM (Kilogramm), MTR (Meter), DAY (Tag). "Stk" oder "piece" fällt bei BR-CL-23 durch.
unitPricenumberPflichtfeldUnit price, net (BT-146). Written to the XML with the decimals you send — at least two, at most what the target format allows. EN 16931 puts no limit on this field (unlike the document totals, which are capped at two decimals), so a price of 1.639 per litre stays 1.639. Formats with a documented limit are capped: FatturaPA 8 decimals, ebInterface 4. A capped price is rounded, and `warnings` carries `PRICE_DECIMALS_ROUNDED` (`lossy: true`) with the field and the written value. Use `priceBaseQuantity` (BT-149) when the price refers to a number of units other than one.
Beispiel: 120
discountobjectoptionalLine item discount (BT-136 to BT-138)
allowancesobject[]optionalLine-level allowances / discounts (BG-27), repeatable. Rendered as `cac:InvoiceLine/cac:AllowanceCharge` with `cbc:ChargeIndicator=false` (UBL) resp. `ram:SpecifiedTradeAllowanceCharge` (CII). Use this instead of `discount` when the line carries more than one reduction or needs a coded reason (BT-140).
chargesobject[]optionalLine-level charges / surcharges (BG-28), repeatable — e.g. packaging or an express surcharge. Rendered with `cbc:ChargeIndicator=true`. There is no `discount`-style short form for charges; this is the only way to express them.
grossPricenumberoptionalItem gross price (BT-148) — the list price BEFORE the price discount, as printed in the catalogue. Together with `priceDiscount` (BT-147) it documents how `unitPrice` (BT-146) came about: BT-147 = BT-148 − BT-146. Rendered as `cac:Price/cac:AllowanceCharge/cbc:BaseAmount`.
Beispiel: 140
priceDiscountnumberoptionalItem price discount (BT-147) — the reduction from `grossPrice` (BT-148) to `unitPrice` (BT-146). Affects the PRICE only; it does not change the line net amount, which is already computed from `unitPrice`. For a reduction that lowers the line total, use `allowances` (BG-27).
Beispiel: 20
priceBaseQuantitynumberoptionalItem price base quantity (BT-149) — the number of units `unitPrice` refers to. `unitPrice: 12, priceBaseQuantity: 100` means "12 per 100 pieces". Omitted means 1.
Beispiel: 100
priceBaseUnitstringoptionalUnit of the price base quantity (BT-150, UN/ECE Rec 20). Defaults to the unit of the line (`unit`) when omitted.
Beispiel: C62
taxRatenumberoptionalTax rate in percent (BT-152, 0..1). Required for every VAT category except "O" (Not subject to VAT), where EN 16931 BR-O-05 forbids it. Omit the field for category O; for every other category it stays mandatory.
Beispiel: 19
taxCategoryCodestringoptionalTax category code (EN 16931: S, Z, E, AE, K, G, O, ...)
Beispiel: S
taxExemptionReasonstringoptionalTax exemption reason free text (BT-120)
Beispiel: Reverse charge — Steuerschuldnerschaft des Leistungsempfängers
taxExemptionReasonCodestringoptionalTax exemption reason code (BT-121, VATEX code)
Beispiel: VATEX-EU-AE
netAmountnumberPflichtfeldNet amount (quantity * unitPrice)
Beispiel: 4800
taxAmountnumberPflichtfeldTax amount
Beispiel: 912
grossAmountnumberoptionalGross amount (net + tax)
Beispiel: 5712
lineSubtypestringoptionalSub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.
Erlaubte Werte: DETAIL, INFORMATION, GROUP
parentLineIdstringoptionalParent line item position reference (BT-X-304, for hierarchical line items)
perPackageQuantitynumberoptionalQuantity per package unit (BT-X-561)
subItemsobject[]optionalNested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals. At most 100 levels deep (400 `SUB_ITEMS_TOO_DEEP`). Sub-items count as lines: all lines together, top-level and nested, may not exceed 25000 (400 `TOO_MANY_INVOICE_LINES`).

items[].classification[]

Item classification (BT-158)

FeldTypPflichtBeschreibung
idstringPflichtfeldClassification code of the item (BT-158).
Beispiel: 65434568
schemeIdstringPflichtfeldIdentification scheme of the classification code (BT-158-1, UNTDID 7143).
Beispiel: TST
schemeVersionstringoptionalVersion of the identification scheme (BT-158-2).
Beispiel: 19.0501

items[].attributes[]

Item attribute (BG-32)

FeldTypPflichtBeschreibung
namestringPflichtfeldName of the item attribute (BT-160).
Beispiel: Farbe
valuestringPflichtfeldValue of the item attribute (BT-161).
Beispiel: blau

items[].servicePeriod

Service period of THIS line (BG-26, BT-134/135). A collective invoice spanning several months needs the period per line — on document level it would be wrong.

FeldTypPflichtBeschreibung
startstringoptionalLine service period start (BT-134, ISO 8601 YYYY-MM-DD).
Beispiel: 2026-03-01
endstringoptionalLine service period end (BT-135, ISO 8601 YYYY-MM-DD).
Beispiel: 2026-03-31

items[].discount

Line item discount (BT-136 to BT-138)

FeldTypPflichtBeschreibung
typestringoptionalDiscount type: percentage or absolute amount
Erlaubte Werte: percentage, absolute
valuenumberoptionalDiscount value
Beispiel: 50
reasonstringoptionalDiscount reason (BT-139)
Beispiel: Mengenrabatt

items[].allowances[]

Line-level allowance (BG-27) or charge (BG-28)

FeldTypPflichtBeschreibung
amountnumberPflichtfeldAmount of the allowance/charge (BT-136 / BT-141), in the invoice currency.
Beispiel: 100
baseAmountnumberoptionalBase amount the percentage applies to (BT-137 / BT-142).
Beispiel: 1000
percentagenumberoptionalPercentage of the allowance/charge (BT-138 / BT-143).
Beispiel: 10
reasonstringoptionalReason for the allowance/charge in clear text (BT-139 / BT-144).
Beispiel: Mengenrabatt
reasonCodestringoptionalCoded reason for the allowance (BT-140, UNCL 5189) resp. the charge (BT-145, UNCL 7161). Several CIUS require the code when the reason is codeable.
Beispiel: 95

items[].charges[]

Line-level allowance (BG-27) or charge (BG-28)

FeldTypPflichtBeschreibung
amountnumberPflichtfeldAmount of the allowance/charge (BT-136 / BT-141), in the invoice currency.
Beispiel: 100
baseAmountnumberoptionalBase amount the percentage applies to (BT-137 / BT-142).
Beispiel: 1000
percentagenumberoptionalPercentage of the allowance/charge (BT-138 / BT-143).
Beispiel: 10
reasonstringoptionalReason for the allowance/charge in clear text (BT-139 / BT-144).
Beispiel: Mengenrabatt
reasonCodestringoptionalCoded reason for the allowance (BT-140, UNCL 5189) resp. the charge (BT-145, UNCL 7161). Several CIUS require the code when the reason is codeable.
Beispiel: 95

taxSummary[]

FeldTypPflichtBeschreibung
taxRatenumberoptionalTax rate in percent (BT-119, 0..1). Required for every VAT category except "O" (Not subject to VAT), which carries no rate.
Beispiel: 19
taxCategoryCodestringoptionalTax category code
Beispiel: S
netAmountnumberPflichtfeldNet amount for this tax rate
Beispiel: 4800
taxAmountnumberPflichtfeldTax amount
Beispiel: 912
exemptionReasonstringoptionalTax exemption reason free text (BT-120)
Beispiel: Reverse charge
exemptionReasonCodestringoptionalTax exemption reason code (BT-121, VATEX code)
Beispiel: VATEX-EU-AE
taxCurrencyTaxAmountnumberoptionalTax amount of this rate in the tax currency (invoice-level `taxCurrencyCode`, BT-6). Austria (ebInterface 6.1): if the invoice currency is not EUR, set `taxCurrencyCode` to "EUR" and give this amount for every rate, otherwise the call is rejected with 422 `AT_EBI_TAX_EUR_AMOUNT_REQUIRED` (rule AT-EBI61-011). No exchange rate is applied.
Beispiel: 812.5

paymentTerms

Payment terms

FeldTypPflichtBeschreibung
dueDaysnumberoptionalPayment due in days
Beispiel: 30
descriptionstringoptionalPayment terms description
Beispiel: Zahlbar innerhalb von 30 Tagen ohne Abzug
earlyPaymentDiscountobjectoptionalEarly payment discount (Skonto). E.g., 2% discount if paid within 10 days. Takes precedence over the top-level cashDiscount* fields when both are present.

paymentTerms.earlyPaymentDiscount

Early payment discount (Skonto). E.g., 2% discount if paid within 10 days. Takes precedence over the top-level cashDiscount* fields when both are present.

FeldTypPflichtBeschreibung
daysintegerPflichtfeldDiscount valid within this many days (integer, 0..365)
Beispiel: 10
discountPercentnumberPflichtfeldDiscount percentage (Skonto) — > 0, <= 100, at most two decimals
Beispiel: 2
baseAmountnumberoptionalOptional base amount the discount is computed from, when it is not the payable amount (BT-115) — e.g. a partial amount on German construction invoices with retention. Emitted as the BASISBETRAG segment of the XRechnung #SKONTO# line (BR-DE-18). Omit it when the discount applies to the full payable amount.
Beispiel: 9500

paymentMethods[]

Payment method

FeldTypPflichtBeschreibung
typestringPflichtfeldPayment method type. When `countrySpecific.paymentMeansCode` is not set, the first entry sets the payment means code (BT-81, UNTDID 4461) in XRechnung, ZUGFeRD and UBL/Peppol: direct_debit=49 (Direct debit), credit_card=54 (Credit card, only together with `cardAccount`), cash=10, paypal=68 (Online payment service), danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1. bank_transfer / credit_transfer keep the format default: 58 (SEPA credit transfer) in German formats, 30 (Credit transfer) elsewhere. If the target format rejects the derived code (for example 49 without `directDebitMandate`), the document keeps the default and carries the warning PAYMENT_MEANS_CODE_NOT_DERIVED. The same happens when the format would drop your payee account (BG-17) for the derived code (XRechnung and ZUGFeRD write it only for credit transfer). With a card or direct debit the code stays and the warning PAYEE_ACCOUNT_NOT_WRITTEN says the account was left out. credit_card without `cardAccount` carries CARD_ACCOUNT_REQUIRED. An explicit `countrySpecific.paymentMeansCode` always wins. Factur-X, Facturae and FatturaPA map the type with their own tables.
Erlaubte Werte: bank_transfer, credit_transfer, direct_debit, credit_card, paypal, cash, danish_fik, giro, other
detailsstringoptionalAdditional details (e.g., "PayPal: invoice@example.com")
Beispiel: SEPA-Überweisung

allowancesCharges[]

Invoice-level allowance (discount) or charge (surcharge)

FeldTypPflichtBeschreibung
isChargebooleanPflichtfeldtrue = surcharge (BG-21), false = discount/allowance (BG-20)
Beispiel: false
amountnumberPflichtfeldAllowance/charge amount (BT-92 / BT-99)
Beispiel: 100
percentagenumberoptionalPercentage (BT-94 / BT-101) — alternative to fixed amount
Beispiel: 5
baseAmountnumberoptionalBase amount for percentage calculation (BT-93 / BT-100)
Beispiel: 2000
reasonstringoptionalReason text (BT-97 / BT-104)
Beispiel: Gesamtrabatt
reasonCodestringoptionalReason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)
Beispiel: 95
taxCategoryCodestringoptionalTax category code (BT-95 / BT-102)
Beispiel: S
taxRatenumberoptionalTax rate in percent (BT-96 / BT-103)
Beispiel: 19

delivery

Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).

FeldTypPflichtBeschreibung
datestringoptionalDelivery date (BT-72, ISO 8601)
Beispiel: 2026-03-20
namestringoptionalDeliver-to party name (BT-70)
Beispiel: Lager Nord
locationIdstringoptionalDelivery location identifier (BT-71)
addressobjectoptionalDelivery address (BG-15)

delivery.address

Delivery address (BG-15)

FeldTypPflichtBeschreibung
streetstringoptionalDelivery street (BT-75)
Beispiel: Lagerstraße 10
additionalStreetstringoptionalAdditional delivery address line (BT-76)
citystringoptionalDelivery city (BT-77)
Beispiel: Hamburg
postalCodestringoptionalDelivery postal code (BT-78)
Beispiel: 20457
statestringoptionalDelivery state/region (BT-79). More than 100 characters: warning `FIELD_TOO_LONG` (field `delivery.address.state`), the value is written unchanged; a later release rejects it with 400.
addressLine3stringoptionalThird delivery address line (BT-165)
Beispiel: Tor 3, Rampe 2
countryCodestringoptionalDelivery country code (BT-80)
Beispiel: DE

directDebitMandate

Direct debit mandate (BG-19). Send it with direct_debit: most formats (XRechnung, Peppol PEPPOL-EN16931-R061) require the mandate reference for payment means code 49 and 59.

FeldTypPflichtBeschreibung
mandateIdstringPflichtfeldSEPA mandate reference (BT-89)
Beispiel: MANDATE-2026-001
creditorIdstringoptionalSEPA creditor identifier (BT-90, 0..1). Optional in EN 16931 — required only by national rules (BR-DE-30 for XRechnung, DE-R-030 for German suppliers in Peppol BIS), which are reported against the generated document.
Beispiel: DE98ZZZ09999999999
debitAccountIdstringoptionalDebited account IBAN (BT-91)
Beispiel: DE89370400440532013000

cardAccount

Card payment details (BG-18). Set it together with a card payment means code (BT-81 = 48, 54 or 55). Formats that cannot represent the group report a GROUP_NOT_REPRESENTABLE warning instead of dropping it silently.

FeldTypPflichtBeschreibung
panstringPflichtfeldBT-87 — masked card primary account number. BR-51 forbids the full PAN: PCI allows the first 6 and last 4 digits to be shown, so at most 10 digits — mask characters do not count towards that limit.
Beispiel: ************1234
holderNamestringoptionalBT-88 — name of the card holder
Beispiel: Max Mustermann
networkIdstringoptionalCard network identifier (cbc:NetworkID; no EN 16931 business term)
Beispiel: VISA

supportingDocuments[]

Reference to a supporting document without the file itself (BT-122/BT-123)

FeldTypPflichtBeschreibung
idstringPflichtfeldBT-122 — identifier of the supporting document
Beispiel: CUSTOMS-2026-000123
descriptionstringoptionalBT-123 — description of the supporting document
Beispiel: Customs declaration
registryIdstringoptionalRegistry/access-point identifier (cbc:UUID). Required in Oman for the prepayment document and for an export invoice with VATZR-OM-12 (IBR-013-OM).
Beispiel: 3f2b9c1e-7d4a-4a1b-9c8e-2f0a5b6d7e8f

retention

Security retention. Reduces only the payment, never the totals or the VAT. Written as a sentence into the payment terms (BT-20 or the national equivalent) of every e-invoice format that has payment terms, in the language of the seller (machine-translated for FR, NL, IT, ES, PL; English for other languages). A reason you send is used as given and is not translated. Do not use allowancesCharges for it. Formats or profiles without payment terms (ZUGFeRD and Factur-X MINIMUM, and myDATA without a payment method) reject the request with 422 (RETENTION_NOT_CARRIED); a plain PDF is not affected.

FeldTypPflichtBeschreibung
amountnumberPflichtfeldRetained amount. Reduces only the amount to pay, never the totals or the VAT.
Beispiel: 500
percentnumberoptionalRetention rate in percent, if you want it named in the sentence
Beispiel: 5
baseAmountnumberoptionalAmount the retention rate refers to, if it is not the invoice total
Beispiel: 10000
reasonstringoptionalReason for the retention. Written as sent, never translated.
Beispiel: Sicherheitseinbehalt gemaess Bauvertrag
dueDatestringoptionalDate the retained amount becomes due (ISO 8601: YYYY-MM-DD)
Beispiel: 2028-06-30

prepayments[]

A single prepayment (BT-113 in detail)

FeldTypPflichtBeschreibung
amountnumberPflichtfeldAmount already paid
Beispiel: 100
paidAtstringoptionalDate the prepayment was received (ISO 8601: YYYY-MM-DD)
Beispiel: 2026-03-01
referenceobjectoptionalReference to the prepayment invoice

prepayments[].reference

Reference to the prepayment invoice

FeldTypPflichtBeschreibung
documentNumberstringPflichtfeldInvoice number of the prepayment document
Beispiel: PRE-2026-0001
registryIdstringoptionalRegistry/access-point identifier of the prepayment document. Required in Oman (IBR-011-OM); the country gate says when.
Beispiel: 3f2b9c1e-7d4a-4a1b-9c8e-2f0a5b6d7e8f

deliveryNote

Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.

FeldTypPflichtBeschreibung
numberstringPflichtfeldDespatch advice / delivery note number (BT-16).
Beispiel: LS-2026-4711
datestringoptionalDespatch advice / delivery note date (BT-17, ISO 8601).
Beispiel: 2026-03-19

thirdPartyPayments[]

Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)

FeldTypPflichtBeschreibung
typestringPflichtfeldThird-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., "voucher", "loyalty", "partial").
Beispiel: voucher
paidAmountnumberPflichtfeldAmount already paid by the third party (BT-DEX-002).
Beispiel: 25
descriptionstringPflichtfeldHuman-readable description of the third-party payment (BT-DEX-003).
Beispiel: Geschenkgutschein eingelöst

attachments[]

Supporting document (BG-24 / BT-122..125): embedded file, external reference, or both

FeldTypPflichtBeschreibung
filenamestringoptionalAttachment filename (BT-125-2). Together with `mimeType` and `content`, or none of the three.
Beispiel: leistungsnachweis.pdf
mimeTypestringoptionalIANA media type of the attachment (BT-125-1). Together with `filename` and `content`, or none of the three.
Beispiel: application/pdf
contentstringoptionalBase64-encoded binary content of the attachment (BT-125, 0..1). Send `content`, `mimeType` and `filename` together, or none of them for a reference without an embedded file (BT-122/BT-124). The whole request body is limited to 128 MiB (413 `PAYLOAD_TOO_LARGE` with `limit`); base64 adds a third, so all attachments together stay below about 95 MiB decoded. More than 20,971,520 base64 characters (15 MiB decoded) in one attachment, or more than 41,943,040 (30 MiB decoded) in all attachments together: warning `FIELD_TOO_LONG` (field `attachments[i].content` or `attachments[*].content`, `maximum` in characters); the invoice is processed unchanged, a later release rejects it with 400.
Beispiel: JVBERi0xLjcKJeLjz9MK...
descriptionstringoptionalOptional human-readable description of the attachment (BT-123).
Beispiel: Stundennachweis März 2026
referencestringoptionalIdentifier of the supporting document (BT-122).
Beispiel: ANL-2026-0042
uristringoptionalExternal location of the supporting document (BT-124). Rendered as `cac:Attachment/cac:ExternalReference/cbc:URI` (UBL) or `ram:URIID` (CII). A reference without an embedded file sends `uri` and/or `reference` and leaves out `content`, `mimeType` and `filename`.
Beispiel: https://muster.de/nachweise/2026-03.pdf

constructionTax

German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.

FeldTypPflichtBeschreibung
exemptionCertificateNumberstringoptionalFreistellungsbescheinigung number per §48b EStG. When set, the generator emits a "#FREISTELLUNG#" note documenting the construction-withholding exemption.
Beispiel: FB-2026-0042
withholdingPercentnumberoptionalConstruction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.
Beispiel: 15
recipientTaxOfficestringoptionalTax office responsible for the recipient of the construction service.
Beispiel: Finanzamt München

countrySpecific

Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.

FeldTypPflichtBeschreibung
countryCodestringoptionalISO 3166-1 alpha-2 country code identifying this country-specific block. Optional — when omitted it is taken from the country in the request path.
Beispiel: DE
Wird countrySpecific gesetzt, ist countryCode darin Pflicht — auch wenn der Ländercode bereits im Pfad steht.
invoiceTypeCodestringoptionalBT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.
Beispiel: 326
transactionTypestringoptionalBTOM-001 Oman invoice transaction type — a 20-character binary mask carried as the `@name` attribute on the document type code. Positions (1-based): 1 full tax, 2 simplified, 3 self-billed, 4 third party, 5 summary, 6 continuous, 7 export, 8 deemed, 9 import RCM, 10 profit margin, 11 profit margin self-billed, 12 e-commerce, 13 import of goods, 14 special zone, 15 prepayment. When omitted the generator writes the standard tax invoice mask.
Beispiel: 10000010000000000000
peppolEndpointIdanyoptionalDeprecated (AE, AU, BE, NZ), a string. countrySpecific.peppolEndpointId is deprecated and is not written. Use buyer.electronicAddress (the seller uses seller.electronicAddress). A request that still sends it is accepted and the response carries a `FIELD_NOT_WRITTEN` warning. The field will be removed in a later release.

Die vollständige Spezifikation

Diese Seite zeigt das invoice-Objekt. Die vollständige OpenAPI-Spezifikation mit allen Endpunkten liegt als Datei bereit — für Code-Generatoren, Postman oder den eigenen Editor.

openapi-full.json öffnen