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.

262

Felder

Pflichtfelder auf invoice

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

Feld	Typ	Pflicht	Beschreibung
`invoiceNumber`	string	Pflichtfeld	Unique invoice number Beispiel: `INV-2026-0042`
`type`	string	Pflichtfeld	Invoice 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`
`issueDate`	string	Pflichtfeld	Issue date (ISO 8601: YYYY-MM-DD) Beispiel: `2026-03-20`
`dueDate`	string	optional	Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given. Beispiel: `2026-04-19`
`deliveryDate`	string	optional	Delivery/service date (ISO 8601) Beispiel: `2026-03-20`
`servicePeriod` Felder ansehen	object	optional	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.
`seller` Felder ansehen	object	Pflichtfeld	Seller party information
`buyer` Felder ansehen	object	Pflichtfeld	Buyer party information
`payee` Felder ansehen	object	optional	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.
`items` Felder ansehen	object[]	Pflichtfeld	Invoice 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`.
`currency`	string	Pflichtfeld	Currency code (ISO 4217) Beispiel: `EUR`
`subtotal`	number	Pflichtfeld	Total net amount Beispiel: `4800`
`total`	number	Pflichtfeld	Total gross amount Beispiel: `5712`
`taxSummary` Felder ansehen	object[]	Pflichtfeld	Tax summary per tax rate
`paymentTerms` Felder ansehen	object	optional	Payment terms
`cashDiscountPercent`	number	optional	Cash 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`
`cashDiscountDays`	integer	optional	Days within which the cash discount applies (integer, 0..365). Beispiel: `14`
`cashDiscountBaseAmount`	number	optional	Optional base amount for the cash discount when it is not the payable amount (BASISBETRAG segment, BR-DE-18). Beispiel: `9500`
`paymentMethods` Felder ansehen	object[]	optional	Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.
`orderNumber`	string	optional	Purchase order number (Bestellnummer) Beispiel: `PO-2026-0815`
`customerNumber`	string	optional	Customer number at the seller Beispiel: `KD-42`
`contractNumber`	string	optional	Contract number (BT-12) Beispiel: `V-2025-1234`
`projectNumber`	string	optional	Project reference (BT-11) Beispiel: `PROJ-2026-42`
`tenderReference`	string	optional	Tender or lot reference (BT-17). Several public contracting authorities reject an invoice without it. Rendered as `cac:OriginatorDocumentReference`. Beispiel: `VgV-2026-042`
`objectId`	string	optional	Object 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`
`objectIdScheme`	string	optional	Scheme of the object identifier (BT-18-1, UNTDID 1153). Beispiel: `AAJ`
`businessProcess`	string	optional	Business 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`
`roundingAmount`	number	optional	Rounding amount (BT-114) Beispiel: `0.01`
`prepaidAmount`	number	optional	Amount 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`
`allowancesCharges` Felder ansehen	object[]	optional	Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.
`delivery` Felder ansehen	object	optional	Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).
`directDebitMandate` Felder ansehen	object	optional	SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.
`cardAccount` Felder ansehen	object	optional	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.
`supportingDocuments` Felder ansehen	object[]	optional	References 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.
`retention` Felder ansehen	object	optional	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.
`prepayments` Felder ansehen	object[]	optional	The 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.
`notes`	string	optional	Additional notes displayed on the invoice Beispiel: `Vielen Dank für Ihren Auftrag!`
`profile`	string	optional	XRechnung 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`
`referencedInvoiceNumber`	string	optional	Number 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`
`referencedInvoiceDate`	string	optional	Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`. Beispiel: `2026-03-15`
`deliveryNote` Felder ansehen	object	optional	Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.
`thirdPartyPayments` Felder ansehen	object[]	optional	Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.
`attachments` Felder ansehen	object[]	optional	Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.
`serviceCategory`	string	optional	Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: "AE"`, the generator emits the §13b UStG reverse-charge note automatically. Erlaubte Werte: `construction, general`
`constructionTax` Felder ansehen	object	optional	German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.
`countrySpecific` Felder ansehen	object	optional	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.

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.

Feld	Typ	Pflicht	Beschreibung
`start`	string	optional	Period start (BT-73, ISO 8601: YYYY-MM-DD) Beispiel: `2026-03-01`
`end`	string	optional	Period end (BT-74, ISO 8601: YYYY-MM-DD) Beispiel: `2026-03-31`

seller

Seller party information

Feld	Typ	Pflicht	Beschreibung
`name`	string	Pflichtfeld	Legal name of the party Beispiel: `Muster GmbH`
`tradingName`	string	optional	Trading name (if different from legal name) Beispiel: `Muster Shop`
`street`	string	optional	Street 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`
`additionalStreet`	string	optional	Additional 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`
`addressLine3`	string	optional	Third address line (BT-162 seller / BT-163 buyer / BT-164 tax representative). Beispiel: `Gebaeude C`
`city`	string	optional	City. 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`
`postalCode`	string	optional	Postal 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`
`countryCode`	string	Pflichtfeld	Country code (ISO 3166-1 alpha-2) Beispiel: `DE`
`state`	string	optional	State/region (ISO 3166-2) Beispiel: `BE`
`taxId`	string	optional	National 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`
`vatId`	string	optional	VAT 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`
`registrationNumber`	string	optional	Public 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`
`registrationScheme`	string	optional	ISO 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`
`identifiers` Felder ansehen	object[]	optional	Further 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.
`email`	string	optional	Email address Beispiel: `billing@muster.de`
`phone`	string	optional	Phone number Beispiel: `+49 30 12345678`
`website`	string	optional	Website URL Beispiel: `https://muster.de`
`contact` Felder ansehen	object	optional	Structured contact person (BG-6 for seller, BG-9 for buyer)
`bankAccount` Felder ansehen	object	optional	Bank 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)

Feld	Typ	Pflicht	Beschreibung
`id`	string	Pflichtfeld	Identifier of the party (BT-29 seller / BT-46 buyer). Beispiel: `4012345000009`
`schemeId`	string	optional	Identification 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)

Feld	Typ	Pflicht	Beschreibung
`name`	string	optional	Contact person name Beispiel: `Max Mustermann`
`phone`	string	optional	Contact phone number Beispiel: `+49 30 12345678`
`email`	string	optional	Contact email address Beispiel: `max@muster.de`
`department`	string	optional	Department 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.

Feld	Typ	Pflicht	Beschreibung
`iban`	string	Pflichtfeld	IBAN (International Bank Account Number) Beispiel: `DE89370400440532013000`
`bic`	string	optional	BIC/SWIFT code (8 or 11 characters) Beispiel: `COBADEFFXXX`
`bankName`	string	optional	Name of the bank Beispiel: `Commerzbank`
`accountHolder`	string	optional	Account holder name (if different from party name) Beispiel: `TechCorp GmbH`

buyer

Buyer party information

Feld	Typ	Pflicht	Beschreibung
`name`	string	Pflichtfeld	Legal name of the party Beispiel: `Muster GmbH`
`tradingName`	string	optional	Trading name (if different from legal name) Beispiel: `Muster Shop`
`street`	string	optional	Street 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`
`additionalStreet`	string	optional	Additional 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`
`addressLine3`	string	optional	Third address line (BT-162 seller / BT-163 buyer / BT-164 tax representative). Beispiel: `Gebaeude C`
`city`	string	optional	City. 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`
`postalCode`	string	optional	Postal 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`
`countryCode`	string	Pflichtfeld	Country code (ISO 3166-1 alpha-2) Beispiel: `DE`
`state`	string	optional	State/region (ISO 3166-2) Beispiel: `BE`
`taxId`	string	optional	National 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`
`vatId`	string	optional	VAT 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`
`registrationNumber`	string	optional	Public 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`
`registrationScheme`	string	optional	ISO 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`
`identifiers` Felder ansehen	object[]	optional	Further 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.
`email`	string	optional	Email address Beispiel: `billing@muster.de`
`phone`	string	optional	Phone number Beispiel: `+49 30 12345678`
`website`	string	optional	Website URL Beispiel: `https://muster.de`
`contact` Felder ansehen	object	optional	Structured contact person (BG-6 for seller, BG-9 for buyer)
`bankAccount` Felder ansehen	object	optional	Bank 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.

buyer.identifiers[]

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

Feld	Typ	Pflicht	Beschreibung
`id`	string	Pflichtfeld	Identifier of the party (BT-29 seller / BT-46 buyer). Beispiel: `4012345000009`
`schemeId`	string	optional	Identification 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)

Feld	Typ	Pflicht	Beschreibung
`name`	string	optional	Contact person name Beispiel: `Max Mustermann`
`phone`	string	optional	Contact phone number Beispiel: `+49 30 12345678`
`email`	string	optional	Contact email address Beispiel: `max@muster.de`
`department`	string	optional	Department 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.

Feld	Typ	Pflicht	Beschreibung
`iban`	string	Pflichtfeld	IBAN (International Bank Account Number) Beispiel: `DE89370400440532013000`
`bic`	string	optional	BIC/SWIFT code (8 or 11 characters) Beispiel: `COBADEFFXXX`
`bankName`	string	optional	Name of the bank Beispiel: `Commerzbank`
`accountHolder`	string	optional	Account 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.

Feld	Typ	Pflicht	Beschreibung
`name`	string	optional	Payee name (BT-59). Required by BR-17 when a payee is given. Beispiel: `Factoring AG`
`tradingName`	string	optional	Trading name (if different from legal name) Beispiel: `Muster Shop`
`street`	string	optional	Street address of the payee
`additionalStreet`	string	optional	Additional address line of the payee
`addressLine3`	string	optional	Third address line (BT-162 seller / BT-163 buyer / BT-164 tax representative). Beispiel: `Gebaeude C`
`city`	string	optional	City of the payee. Required on the CH/LI QR bill (`qr-bill`): without it 422 `CH_ADDR_005`, field `payee.city`.
`postalCode`	string	optional	Postal code of the payee. Required on the CH/LI QR bill (`qr-bill`): without it 422 `CH_ADDR_004`, field `payee.postalCode`.
`countryCode`	string	optional	Country 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`.
`state`	string	optional	State/region (ISO 3166-2) Beispiel: `BE`
`taxId`	string	optional	National 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`
`vatId`	string	optional	VAT 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`
`registrationNumber`	string	optional	Public 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`
`registrationScheme`	string	optional	ISO 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`
`identifiers` Felder ansehen	object[]	optional	Payee identifiers (BT-60). Only the first non-empty entry is written; further entries give `FIELD_NOT_WRITTEN` (field `payee.identifiers.<n>`).
`email`	string	optional	Email address Beispiel: `billing@muster.de`
`phone`	string	optional	Phone number Beispiel: `+49 30 12345678`
`website`	string	optional	Website URL Beispiel: `https://muster.de`
`contact` Felder ansehen	object	optional	Structured contact person (BG-6 for seller, BG-9 for buyer)
`bankAccount` Felder ansehen	object	optional	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`.

payee.identifiers[]

Feld	Typ	Pflicht	Beschreibung
`id`	string	optional	Identifier of the payee (BT-60). Empty entries are skipped. Beispiel: `4012345000009`
`schemeId`	string	optional	Identification 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)

Feld	Typ	Pflicht	Beschreibung
`name`	string	optional	Contact person name Beispiel: `Max Mustermann`
`phone`	string	optional	Contact phone number Beispiel: `+49 30 12345678`
`email`	string	optional	Contact email address Beispiel: `max@muster.de`
`department`	string	optional	Department 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`.

Feld	Typ	Pflicht	Beschreibung
`iban`	string	Pflichtfeld	IBAN (International Bank Account Number) Beispiel: `DE89370400440532013000`
`bic`	string	optional	BIC/SWIFT code (8 or 11 characters) Beispiel: `COBADEFFXXX`
`bankName`	string	optional	Name of the bank Beispiel: `Commerzbank`
`accountHolder`	string	optional	Account holder name (if different from party name) Beispiel: `TechCorp GmbH`

items[]

Feld	Typ	Pflicht	Beschreibung
`position`	integer	optional	Line item position number (BT-126 — zero-indexed line IDs are valid) Beispiel: `1`
`description`	string	Pflichtfeld	Item description Beispiel: `Software Development Services — March 2026`
`articleNumber`	string	optional	Article/SKU number — the SELLER's item identifier (BT-155). Beispiel: `SVC-DEV-001`
`gtin`	string	optional	Global Trade Item Number (BT-157). Rendered as `cac:StandardItemIdentification/cbc:ID` with `schemeID="0160"`. Beispiel: `04012345678901`
`itemDescription`	string	optional	Longer 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.`
`buyerItemId`	string	optional	Item 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`
`classification` Felder ansehen	object[]	optional	Item classifications (BT-158), repeatable — e.g. UNSPSC, eCl@ss, eTIM.
`originCountry`	string	optional	Country of origin of the item (BT-159, ISO 3166-1 alpha-2). Beispiel: `CN`
`attributes` Felder ansehen	object[]	optional	Item attributes (BG-32), repeatable — name and value, both required.
`note`	string	optional	Free-text note for THIS line (BT-127). Beispiel: `Leistung erbracht am 12. und 13. Maerz, Nachweis anbei.`
`objectId`	string	optional	Object 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`
`objectIdScheme`	string	optional	Scheme of the object identifier (BT-128-1, UNTDID 1153). Beispiel: `AAJ`
`orderLineReference`	string	optional	Referenced purchase order line number (BT-132). Beispiel: `5`
`buyerAccountingReference`	string	optional	Buyer's accounting reference / cost centre for this line (BT-133). Beispiel: `KST-4711`
`servicePeriod` Felder ansehen	object	optional	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.
`quantity`	number	Pflichtfeld	Quantity (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. Beispiel: `40`
`unit`	string	Pflichtfeld	Unit 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.
`unitPrice`	number	Pflichtfeld	Unit 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. Use `priceBaseQuantity` (BT-149) when the price refers to a number of units other than one. Beispiel: `120`
`discount` Felder ansehen	object	optional	Line item discount (BT-136 to BT-138)
`allowances` Felder ansehen	object[]	optional	Line-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).
`charges` Felder ansehen	object[]	optional	Line-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.
`grossPrice`	number	optional	Item 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`
`priceDiscount`	number	optional	Item 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`
`priceBaseQuantity`	number	optional	Item 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`
`priceBaseUnit`	string	optional	Unit of the price base quantity (BT-150, UN/ECE Rec 20). Defaults to the unit of the line (`unit`) when omitted. Beispiel: `C62`
`taxRate`	number	optional	Tax 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`
`taxCategoryCode`	string	optional	Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...) Beispiel: `S`
`taxExemptionReason`	string	optional	Tax exemption reason free text (BT-120) Beispiel: `Reverse charge — Steuerschuldnerschaft des Leistungsempfängers`
`taxExemptionReasonCode`	string	optional	Tax exemption reason code (BT-121, VATEX code) Beispiel: `VATEX-EU-AE`
`netAmount`	number	Pflichtfeld	Net amount (quantity * unitPrice) Beispiel: `4800`
`taxAmount`	number	Pflichtfeld	Tax amount Beispiel: `912`
`grossAmount`	number	optional	Gross amount (net + tax) Beispiel: `5712`
`lineSubtype`	string	optional	Sub-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`
`parentLineId`	string	optional	Parent line item position reference (BT-X-304, for hierarchical line items)
`perPackageQuantity`	number	optional	Quantity per package unit (BT-X-561)
`subItems` Gleiche Felder wie eine Position	object[]	optional	Nested 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)

Feld	Typ	Pflicht	Beschreibung
`id`	string	Pflichtfeld	Classification code of the item (BT-158). Beispiel: `65434568`
`schemeId`	string	Pflichtfeld	Identification scheme of the classification code (BT-158-1, UNTDID 7143). Beispiel: `TST`
`schemeVersion`	string	optional	Version of the identification scheme (BT-158-2). Beispiel: `19.0501`

items[].attributes[]

Item attribute (BG-32)

Feld	Typ	Pflicht	Beschreibung
`name`	string	Pflichtfeld	Name of the item attribute (BT-160). Beispiel: `Farbe`
`value`	string	Pflichtfeld	Value 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.

Feld	Typ	Pflicht	Beschreibung
`start`	string	optional	Line service period start (BT-134, ISO 8601 YYYY-MM-DD). Beispiel: `2026-03-01`
`end`	string	optional	Line service period end (BT-135, ISO 8601 YYYY-MM-DD). Beispiel: `2026-03-31`

items[].discount

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

Feld	Typ	Pflicht	Beschreibung
`type`	string	optional	Discount type: percentage or absolute amount Erlaubte Werte: `percentage, absolute`
`value`	number	optional	Discount value Beispiel: `50`
`reason`	string	optional	Discount reason (BT-139) Beispiel: `Mengenrabatt`

items[].allowances[]

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

Feld	Typ	Pflicht	Beschreibung
`amount`	number	Pflichtfeld	Amount of the allowance/charge (BT-136 / BT-141), in the invoice currency. Beispiel: `100`
`baseAmount`	number	optional	Base amount the percentage applies to (BT-137 / BT-142). Beispiel: `1000`
`percentage`	number	optional	Percentage of the allowance/charge (BT-138 / BT-143). Beispiel: `10`
`reason`	string	optional	Reason for the allowance/charge in clear text (BT-139 / BT-144). Beispiel: `Mengenrabatt`
`reasonCode`	string	optional	Coded 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)

Feld	Typ	Pflicht	Beschreibung
`amount`	number	Pflichtfeld	Amount of the allowance/charge (BT-136 / BT-141), in the invoice currency. Beispiel: `100`
`baseAmount`	number	optional	Base amount the percentage applies to (BT-137 / BT-142). Beispiel: `1000`
`percentage`	number	optional	Percentage of the allowance/charge (BT-138 / BT-143). Beispiel: `10`
`reason`	string	optional	Reason for the allowance/charge in clear text (BT-139 / BT-144). Beispiel: `Mengenrabatt`
`reasonCode`	string	optional	Coded 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[]

Feld	Typ	Pflicht	Beschreibung
`taxRate`	number	optional	Tax rate in percent (BT-119, 0..1). Required for every VAT category except "O" (Not subject to VAT), which carries no rate. Beispiel: `19`
`taxCategoryCode`	string	optional	Tax category code Beispiel: `S`
`netAmount`	number	Pflichtfeld	Net amount for this tax rate Beispiel: `4800`
`taxAmount`	number	Pflichtfeld	Tax amount Beispiel: `912`
`exemptionReason`	string	optional	Tax exemption reason free text (BT-120) Beispiel: `Reverse charge`
`exemptionReasonCode`	string	optional	Tax exemption reason code (BT-121, VATEX code) Beispiel: `VATEX-EU-AE`
`taxCurrencyTaxAmount`	number	optional	Tax 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

Feld	Typ	Pflicht	Beschreibung
`dueDays`	number	optional	Payment due in days Beispiel: `30`
`description`	string	optional	Payment terms description Beispiel: `Zahlbar innerhalb von 30 Tagen ohne Abzug`
`earlyPaymentDiscount` Felder ansehen	object	optional	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.

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.

Feld	Typ	Pflicht	Beschreibung
`days`	integer	Pflichtfeld	Discount valid within this many days (integer, 0..365) Beispiel: `10`
`discountPercent`	number	Pflichtfeld	Discount percentage (Skonto) — > 0, <= 100, at most two decimals Beispiel: `2`
`baseAmount`	number	optional	Optional 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

Feld	Typ	Pflicht	Beschreibung
`type`	string	Pflichtfeld	Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1. Erlaubte Werte: `bank_transfer, credit_transfer, direct_debit, credit_card, paypal, cash, danish_fik, giro, other`
`details`	string	optional	Additional details (e.g., "PayPal: invoice@example.com") Beispiel: `SEPA-Überweisung`

allowancesCharges[]

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

Feld	Typ	Pflicht	Beschreibung
`isCharge`	boolean	Pflichtfeld	true = surcharge (BG-21), false = discount/allowance (BG-20) Beispiel: `false`
`amount`	number	Pflichtfeld	Allowance/charge amount (BT-92 / BT-99) Beispiel: `100`
`percentage`	number	optional	Percentage (BT-94 / BT-101) — alternative to fixed amount Beispiel: `5`
`baseAmount`	number	optional	Base amount for percentage calculation (BT-93 / BT-100) Beispiel: `2000`
`reason`	string	optional	Reason text (BT-97 / BT-104) Beispiel: `Gesamtrabatt`
`reasonCode`	string	optional	Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105) Beispiel: `95`
`taxCategoryCode`	string	optional	Tax category code (BT-95 / BT-102) Beispiel: `S`
`taxRate`	number	optional	Tax 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).

Feld	Typ	Pflicht	Beschreibung
`date`	string	optional	Delivery date (BT-72, ISO 8601) Beispiel: `2026-03-20`
`name`	string	optional	Deliver-to party name (BT-70) Beispiel: `Lager Nord`
`locationId`	string	optional	Delivery location identifier (BT-71)
`address` Felder ansehen	object	optional	Delivery address (BG-15)

delivery.address

Delivery address (BG-15)

Feld	Typ	Pflicht	Beschreibung
`street`	string	optional	Delivery street (BT-75) Beispiel: `Lagerstraße 10`
`additionalStreet`	string	optional	Additional delivery address line (BT-76)
`city`	string	optional	Delivery city (BT-77) Beispiel: `Hamburg`
`postalCode`	string	optional	Delivery postal code (BT-78) Beispiel: `20457`
`state`	string	optional	Delivery state/region (BT-79)
`addressLine3`	string	optional	Third delivery address line (BT-165) Beispiel: `Tor 3, Rampe 2`
`countryCode`	string	optional	Delivery country code (BT-80) Beispiel: `DE`

directDebitMandate

SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.

Feld	Typ	Pflicht	Beschreibung
`mandateId`	string	Pflichtfeld	SEPA mandate reference (BT-89) Beispiel: `MANDATE-2026-001`
`creditorId`	string	optional	SEPA 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`
`debitAccountId`	string	optional	Debited 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.

Feld	Typ	Pflicht	Beschreibung
`pan`	string	Pflichtfeld	BT-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`
`holderName`	string	optional	BT-88 — name of the card holder Beispiel: `Max Mustermann`
`networkId`	string	optional	Card 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)

Feld	Typ	Pflicht	Beschreibung
`id`	string	Pflichtfeld	BT-122 — identifier of the supporting document Beispiel: `CUSTOMS-2026-000123`
`description`	string	optional	BT-123 — description of the supporting document Beispiel: `Customs declaration`
`registryId`	string	optional	Registry/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.

Feld	Typ	Pflicht	Beschreibung
`amount`	number	Pflichtfeld	Retained amount. Reduces only the amount to pay, never the totals or the VAT. Beispiel: `500`
`percent`	number	optional	Retention rate in percent, if you want it named in the sentence Beispiel: `5`
`baseAmount`	number	optional	Amount the retention rate refers to, if it is not the invoice total Beispiel: `10000`
`reason`	string	optional	Reason for the retention. Written as sent, never translated. Beispiel: `Sicherheitseinbehalt gemaess Bauvertrag`
`dueDate`	string	optional	Date the retained amount becomes due (ISO 8601: YYYY-MM-DD) Beispiel: `2028-06-30`

prepayments[]

A single prepayment (BT-113 in detail)

Feld	Typ	Pflicht	Beschreibung
`amount`	number	Pflichtfeld	Amount already paid Beispiel: `100`
`paidAt`	string	optional	Date the prepayment was received (ISO 8601: YYYY-MM-DD) Beispiel: `2026-03-01`
`reference` Felder ansehen	object	optional	Reference to the prepayment invoice

prepayments[].reference

Reference to the prepayment invoice

Feld	Typ	Pflicht	Beschreibung
`documentNumber`	string	Pflichtfeld	Invoice number of the prepayment document Beispiel: `PRE-2026-0001`
`registryId`	string	optional	Registry/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.

Feld	Typ	Pflicht	Beschreibung
`number`	string	Pflichtfeld	Despatch advice / delivery note number (BT-16). Beispiel: `LS-2026-4711`
`date`	string	optional	Despatch 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)

Feld	Typ	Pflicht	Beschreibung
`type`	string	Pflichtfeld	Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., "voucher", "loyalty", "partial"). Beispiel: `voucher`
`paidAmount`	number	Pflichtfeld	Amount already paid by the third party (BT-DEX-002). Beispiel: `25`
`description`	string	Pflichtfeld	Human-readable description of the third-party payment (BT-DEX-003). Beispiel: `Geschenkgutschein eingelöst`

attachments[]

Embedded attachment (BG-24 / BT-122..125)

Feld	Typ	Pflicht	Beschreibung
`filename`	string	Pflichtfeld	Attachment filename (BT-125). Beispiel: `leistungsnachweis.pdf`
`mimeType`	string	Pflichtfeld	IANA media type of the attachment (BT-125-1). Beispiel: `application/pdf`
`content`	string	Pflichtfeld	Base64-encoded binary content of the attachment (BT-125). 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. Beispiel: `JVBERi0xLjcKJeLjz9MK...`
`description`	string	optional	Optional human-readable description of the attachment (BT-123). Beispiel: `Stundennachweis März 2026`
`reference`	string	optional	Identifier of the supporting document (BT-122). Beispiel: `ANL-2026-0042`
`uri`	string	optional	External location of the supporting document (BT-124). Rendered as `cac:Attachment/cac:ExternalReference/cbc:URI`, IN ADDITION to the embedded content — the generators always write the embedded object, so `content` stays required. A URI-only reference is not supported today. 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.

Feld	Typ	Pflicht	Beschreibung
`exemptionCertificateNumber`	string	optional	Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a "#FREISTELLUNG#" note documenting the construction-withholding exemption. Beispiel: `FB-2026-0042`
`withholdingPercent`	number	optional	Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented. Beispiel: `15`
`recipientTaxOffice`	string	optional	Tax 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.

Feld	Typ	Pflicht	Beschreibung
`countryCode`	string	Pflichtfeld	ISO 3166-1 alpha-2 country code identifying this country-specific block. Beispiel: `DE` Wird countrySpecific gesetzt, ist countryCode darin Pflicht — auch wenn der Ländercode bereits im Pfad steht.
`invoiceTypeCode`	string	optional	BT-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`
`transactionType`	string	optional	BTOM-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`
`peppolEndpointId`	any	optional	Deprecated (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

Weiter

Creator API

Rechnungen in 14 Formaten erzeugen

Validator API

Rechnungsdaten gegen die KoSIT-Regeln prüfen

Error Handling

Fehlermeldungen und ihre Ursachen