Referenz

Field reference

Every field of the invoice object that the Creator and Validator APIs accept. This page is generated from the OpenAPI specification, so it cannot drift away from it.

262

fields

required on invoice

objects

Generated from Invoice.xhub API · POST /api/v1/invoice/{countryCode}/{format}/generate

One complete example

The same data the playground on the home page starts with — complete, with every required field.

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}

Three places where integrations get stuck

As soon as paymentMethods contains a credit transfer, EN 16931 (BR-61) requires the payment account identifier. Without seller.bankAccount.iban the invoice is rejected.

The unit of measure is a UN/ECE Rec 20 code, not free text: C62 (piece), HUR (hour), KGM (kilogram), MTR (metre), DAY (day). "Stk" or "piece" fails BR-CL-23.

If countrySpecific is set, countryCode inside it is required — even though the country code is already in the path.

All fields

invoice

Invoice data to generate document from

Field	Type	Required	Description
`invoiceNumber`	string	required	Unique invoice number Example: `INV-2026-0042`
`type`	string	required	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). Allowed values: `invoice, credit_note, proforma, correction, partial, partial_construction, partial_final_construction, final_construction, self_billed`
`issueDate`	string	required	Issue date (ISO 8601: YYYY-MM-DD) Example: `2026-03-20`
`dueDate`	string	optional	Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given. Example: `2026-04-19`
`deliveryDate`	string	optional	Delivery/service date (ISO 8601) Example: `2026-03-20`
`servicePeriod` See fields	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` See fields	object	required	Seller party information
`buyer` See fields	object	required	Buyer party information
`payee` See fields	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` See fields	object[]	required	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	required	Currency code (ISO 4217) Example: `EUR`
`subtotal`	number	required	Total net amount Example: `4800`
`total`	number	required	Total gross amount Example: `5712`
`taxSummary` See fields	object[]	required	Tax summary per tax rate
`paymentTerms` See fields	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. Example: `2`
`cashDiscountDays`	integer	optional	Days within which the cash discount applies (integer, 0..365). Example: `14`
`cashDiscountBaseAmount`	number	optional	Optional base amount for the cash discount when it is not the payable amount (BASISBETRAG segment, BR-DE-18). Example: `9500`
`paymentMethods` See fields	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) Example: `PO-2026-0815`
`customerNumber`	string	optional	Customer number at the seller Example: `KD-42`
`contractNumber`	string	optional	Contract number (BT-12) Example: `V-2025-1234`
`projectNumber`	string	optional	Project reference (BT-11) Example: `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`. Example: `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. Example: `PROJ-7`
`objectIdScheme`	string	optional	Scheme of the object identifier (BT-18-1, UNTDID 1153). Example: `AAJ`
`businessProcess`	string	optional	Business process type (BT-23). Rendered as `cbc:ProfileID`. When omitted the generator emits the profile the target format prescribes. Example: `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
`roundingAmount`	number	optional	Rounding amount (BT-114) Example: `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. Example: `500`
`allowancesCharges` See fields	object[]	optional	Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.
`delivery` See fields	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` See fields	object	optional	SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.
`cardAccount` See fields	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` See fields	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` See fields	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` See fields	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 Example: `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. Allowed values: `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. Example: `INV-2026-0040`
`referencedInvoiceDate`	string	optional	Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`. Example: `2026-03-15`
`deliveryNote` See fields	object	optional	Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.
`thirdPartyPayments` See fields	object[]	optional	Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.
`attachments` See fields	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. Allowed values: `construction, general`
`constructionTax` See fields	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` See fields	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.

Field	Type	Required	Description
`start`	string	optional	Period start (BT-73, ISO 8601: YYYY-MM-DD) Example: `2026-03-01`
`end`	string	optional	Period end (BT-74, ISO 8601: YYYY-MM-DD) Example: `2026-03-31`

seller

Seller party information

Field	Type	Required	Description
`name`	string	required	Legal name of the party Example: `Muster GmbH`
`tradingName`	string	optional	Trading name (if different from legal name) Example: `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. Example: `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. Example: `2. OG, Raum 5`
`addressLine3`	string	optional	Third address line (BT-162 seller / BT-163 buyer / BT-164 tax representative). Example: `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. Example: `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. Example: `10115`
`countryCode`	string	required	Country code (ISO 3166-1 alpha-2) Example: `DE`
`state`	string	optional	State/region (ISO 3166-2) Example: `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. Example: `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. Example: `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. Example: `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. Example: `0198`
`identifiers` See fields	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 Example: `billing@muster.de`
`phone`	string	optional	Phone number Example: `+49 30 12345678`
`website`	string	optional	Website URL Example: `https://muster.de`
`contact` See fields	object	optional	Structured contact person (BG-6 for seller, BG-9 for buyer)
`bankAccount` See fields	object	optional	Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required. As soon as paymentMethods contains a credit transfer, EN 16931 (BR-61) requires the payment account identifier. Without seller.bankAccount.iban the invoice is rejected.

seller.identifiers[]

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

Field	Type	Required	Description
`id`	string	required	Identifier of the party (BT-29 seller / BT-46 buyer). Example: `4012345000009`
`schemeId`	string	optional	Identification scheme of the identifier (BT-29-1 / BT-46-1, ISO 6523 ICD). Example: `0088`

seller.contact

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

Field	Type	Required	Description
`name`	string	optional	Contact person name Example: `Max Mustermann`
`phone`	string	optional	Contact phone number Example: `+49 30 12345678`
`email`	string	optional	Contact email address Example: `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. Example: `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.

Field	Type	Required	Description
`iban`	string	required	IBAN (International Bank Account Number) Example: `DE89370400440532013000`
`bic`	string	optional	BIC/SWIFT code (8 or 11 characters) Example: `COBADEFFXXX`
`bankName`	string	optional	Name of the bank Example: `Commerzbank`
`accountHolder`	string	optional	Account holder name (if different from party name) Example: `TechCorp GmbH`

buyer

Buyer party information

Field	Type	Required	Description
`name`	string	required	Legal name of the party Example: `Muster GmbH`
`tradingName`	string	optional	Trading name (if different from legal name) Example: `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. Example: `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. Example: `2. OG, Raum 5`
`addressLine3`	string	optional	Third address line (BT-162 seller / BT-163 buyer / BT-164 tax representative). Example: `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. Example: `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. Example: `10115`
`countryCode`	string	required	Country code (ISO 3166-1 alpha-2) Example: `DE`
`state`	string	optional	State/region (ISO 3166-2) Example: `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. Example: `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. Example: `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. Example: `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. Example: `0198`
`identifiers` See fields	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 Example: `billing@muster.de`
`phone`	string	optional	Phone number Example: `+49 30 12345678`
`website`	string	optional	Website URL Example: `https://muster.de`
`contact` See fields	object	optional	Structured contact person (BG-6 for seller, BG-9 for buyer)
`bankAccount` See fields	object	optional	Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required. As soon as paymentMethods contains a credit transfer, EN 16931 (BR-61) requires the payment account identifier. Without seller.bankAccount.iban the invoice is rejected.

buyer.identifiers[]

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

Field	Type	Required	Description
`id`	string	required	Identifier of the party (BT-29 seller / BT-46 buyer). Example: `4012345000009`
`schemeId`	string	optional	Identification scheme of the identifier (BT-29-1 / BT-46-1, ISO 6523 ICD). Example: `0088`

buyer.contact

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

Field	Type	Required	Description
`name`	string	optional	Contact person name Example: `Max Mustermann`
`phone`	string	optional	Contact phone number Example: `+49 30 12345678`
`email`	string	optional	Contact email address Example: `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. Example: `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.

Field	Type	Required	Description
`iban`	string	required	IBAN (International Bank Account Number) Example: `DE89370400440532013000`
`bic`	string	optional	BIC/SWIFT code (8 or 11 characters) Example: `COBADEFFXXX`
`bankName`	string	optional	Name of the bank Example: `Commerzbank`
`accountHolder`	string	optional	Account holder name (if different from party name) Example: `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.

Field	Type	Required	Description
`name`	string	optional	Payee name (BT-59). Required by BR-17 when a payee is given. Example: `Factoring AG`
`tradingName`	string	optional	Trading name (if different from legal name) Example: `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). Example: `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) Example: `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. Example: `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. Example: `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). Example: `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. Example: `0198`
`identifiers` See fields	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 Example: `billing@muster.de`
`phone`	string	optional	Phone number Example: `+49 30 12345678`
`website`	string	optional	Website URL Example: `https://muster.de`
`contact` See fields	object	optional	Structured contact person (BG-6 for seller, BG-9 for buyer)
`bankAccount` See fields	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[]

Field	Type	Required	Description
`id`	string	optional	Identifier of the payee (BT-60). Empty entries are skipped. Example: `4012345000009`
`schemeId`	string	optional	Identification scheme of the identifier (BT-29-1 / BT-46-1, ISO 6523 ICD). Example: `0088`

payee.contact

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

Field	Type	Required	Description
`name`	string	optional	Contact person name Example: `Max Mustermann`
`phone`	string	optional	Contact phone number Example: `+49 30 12345678`
`email`	string	optional	Contact email address Example: `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. Example: `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`.

Field	Type	Required	Description
`iban`	string	required	IBAN (International Bank Account Number) Example: `DE89370400440532013000`
`bic`	string	optional	BIC/SWIFT code (8 or 11 characters) Example: `COBADEFFXXX`
`bankName`	string	optional	Name of the bank Example: `Commerzbank`
`accountHolder`	string	optional	Account holder name (if different from party name) Example: `TechCorp GmbH`

items[]

Field	Type	Required	Description
`position`	integer	optional	Line item position number (BT-126 — zero-indexed line IDs are valid) Example: `1`
`description`	string	required	Item description Example: `Software Development Services — March 2026`
`articleNumber`	string	optional	Article/SKU number — the SELLER's item identifier (BT-155). Example: `SVC-DEV-001`
`gtin`	string	optional	Global Trade Item Number (BT-157). Rendered as `cac:StandardItemIdentification/cbc:ID` with `schemeID="0160"`. Example: `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. Example: `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. Example: `KD-ART-9911`
`classification` See fields	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). Example: `CN`
`attributes` See fields	object[]	optional	Item attributes (BG-32), repeatable — name and value, both required.
`note`	string	optional	Free-text note for THIS line (BT-127). Example: `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. Example: `ZAEHLER-4711`
`objectIdScheme`	string	optional	Scheme of the object identifier (BT-128-1, UNTDID 1153). Example: `AAJ`
`orderLineReference`	string	optional	Referenced purchase order line number (BT-132). Example: `5`
`buyerAccountingReference`	string	optional	Buyer's accounting reference / cost centre for this line (BT-133). Example: `KST-4711`
`servicePeriod` See fields	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	required	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. Example: `40`
`unit`	string	required	Unit code (UN/ECE Rec 20) Example: `HUR` The unit of measure is a UN/ECE Rec 20 code, not free text: C62 (piece), HUR (hour), KGM (kilogram), MTR (metre), DAY (day). "Stk" or "piece" fails BR-CL-23.
`unitPrice`	number	required	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. Example: `120`
`discount` See fields	object	optional	Line item discount (BT-136 to BT-138)
`allowances` See fields	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` See fields	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`. Example: `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). Example: `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. Example: `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. Example: `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. Example: `19`
`taxCategoryCode`	string	optional	Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...) Example: `S`
`taxExemptionReason`	string	optional	Tax exemption reason free text (BT-120) Example: `Reverse charge — Steuerschuldnerschaft des Leistungsempfängers`
`taxExemptionReasonCode`	string	optional	Tax exemption reason code (BT-121, VATEX code) Example: `VATEX-EU-AE`
`netAmount`	number	required	Net amount (quantity * unitPrice) Example: `4800`
`taxAmount`	number	required	Tax amount Example: `912`
`grossAmount`	number	optional	Gross amount (net + tax) Example: `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. Allowed values: `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` Same fields as a line item	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)

Field	Type	Required	Description
`id`	string	required	Classification code of the item (BT-158). Example: `65434568`
`schemeId`	string	required	Identification scheme of the classification code (BT-158-1, UNTDID 7143). Example: `TST`
`schemeVersion`	string	optional	Version of the identification scheme (BT-158-2). Example: `19.0501`

items[].attributes[]

Item attribute (BG-32)

Field	Type	Required	Description
`name`	string	required	Name of the item attribute (BT-160). Example: `Farbe`
`value`	string	required	Value of the item attribute (BT-161). Example: `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.

Field	Type	Required	Description
`start`	string	optional	Line service period start (BT-134, ISO 8601 YYYY-MM-DD). Example: `2026-03-01`
`end`	string	optional	Line service period end (BT-135, ISO 8601 YYYY-MM-DD). Example: `2026-03-31`

items[].discount

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

Field	Type	Required	Description
`type`	string	optional	Discount type: percentage or absolute amount Allowed values: `percentage, absolute`
`value`	number	optional	Discount value Example: `50`
`reason`	string	optional	Discount reason (BT-139) Example: `Mengenrabatt`

items[].allowances[]

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

Field	Type	Required	Description
`amount`	number	required	Amount of the allowance/charge (BT-136 / BT-141), in the invoice currency. Example: `100`
`baseAmount`	number	optional	Base amount the percentage applies to (BT-137 / BT-142). Example: `1000`
`percentage`	number	optional	Percentage of the allowance/charge (BT-138 / BT-143). Example: `10`
`reason`	string	optional	Reason for the allowance/charge in clear text (BT-139 / BT-144). Example: `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. Example: `95`

items[].charges[]

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

Field	Type	Required	Description
`amount`	number	required	Amount of the allowance/charge (BT-136 / BT-141), in the invoice currency. Example: `100`
`baseAmount`	number	optional	Base amount the percentage applies to (BT-137 / BT-142). Example: `1000`
`percentage`	number	optional	Percentage of the allowance/charge (BT-138 / BT-143). Example: `10`
`reason`	string	optional	Reason for the allowance/charge in clear text (BT-139 / BT-144). Example: `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. Example: `95`

taxSummary[]

Field	Type	Required	Description
`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. Example: `19`
`taxCategoryCode`	string	optional	Tax category code Example: `S`
`netAmount`	number	required	Net amount for this tax rate Example: `4800`
`taxAmount`	number	required	Tax amount Example: `912`
`exemptionReason`	string	optional	Tax exemption reason free text (BT-120) Example: `Reverse charge`
`exemptionReasonCode`	string	optional	Tax exemption reason code (BT-121, VATEX code) Example: `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. Example: `812.5`

paymentTerms

Payment terms

Field	Type	Required	Description
`dueDays`	number	optional	Payment due in days Example: `30`
`description`	string	optional	Payment terms description Example: `Zahlbar innerhalb von 30 Tagen ohne Abzug`
`earlyPaymentDiscount` See fields	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.

Field	Type	Required	Description
`days`	integer	required	Discount valid within this many days (integer, 0..365) Example: `10`
`discountPercent`	number	required	Discount percentage (Skonto) — > 0, <= 100, at most two decimals Example: `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. Example: `9500`

paymentMethods[]

Payment method

Field	Type	Required	Description
`type`	string	required	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. Allowed values: `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") Example: `SEPA-Überweisung`

allowancesCharges[]

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

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

Field	Type	Required	Description
`date`	string	optional	Delivery date (BT-72, ISO 8601) Example: `2026-03-20`
`name`	string	optional	Deliver-to party name (BT-70) Example: `Lager Nord`
`locationId`	string	optional	Delivery location identifier (BT-71)
`address` See fields	object	optional	Delivery address (BG-15)

delivery.address

Delivery address (BG-15)

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

directDebitMandate

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

Field	Type	Required	Description
`mandateId`	string	required	SEPA mandate reference (BT-89) Example: `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. Example: `DE98ZZZ09999999999`
`debitAccountId`	string	optional	Debited account IBAN (BT-91) Example: `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.

Field	Type	Required	Description
`pan`	string	required	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. Example: `************1234`
`holderName`	string	optional	BT-88 — name of the card holder Example: `Max Mustermann`
`networkId`	string	optional	Card network identifier (cbc:NetworkID; no EN 16931 business term) Example: `VISA`

supportingDocuments[]

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

Field	Type	Required	Description
`id`	string	required	BT-122 — identifier of the supporting document Example: `CUSTOMS-2026-000123`
`description`	string	optional	BT-123 — description of the supporting document Example: `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). Example: `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.

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

prepayments[]

A single prepayment (BT-113 in detail)

Field	Type	Required	Description
`amount`	number	required	Amount already paid Example: `100`
`paidAt`	string	optional	Date the prepayment was received (ISO 8601: YYYY-MM-DD) Example: `2026-03-01`
`reference` See fields	object	optional	Reference to the prepayment invoice

prepayments[].reference

Reference to the prepayment invoice

Field	Type	Required	Description
`documentNumber`	string	required	Invoice number of the prepayment document Example: `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. Example: `3f2b9c1e-7d4a-4a1b-9c8e-2f0a5b6d7e8f`

deliveryNote

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

Field	Type	Required	Description
`number`	string	required	Despatch advice / delivery note number (BT-16). Example: `LS-2026-4711`
`date`	string	optional	Despatch advice / delivery note date (BT-17, ISO 8601). Example: `2026-03-19`

thirdPartyPayments[]

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

Field	Type	Required	Description
`type`	string	required	Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., "voucher", "loyalty", "partial"). Example: `voucher`
`paidAmount`	number	required	Amount already paid by the third party (BT-DEX-002). Example: `25`
`description`	string	required	Human-readable description of the third-party payment (BT-DEX-003). Example: `Geschenkgutschein eingelöst`

attachments[]

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

Field	Type	Required	Description
`filename`	string	required	Attachment filename (BT-125). Example: `leistungsnachweis.pdf`
`mimeType`	string	required	IANA media type of the attachment (BT-125-1). Example: `application/pdf`
`content`	string	required	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. Example: `JVBERi0xLjcKJeLjz9MK...`
`description`	string	optional	Optional human-readable description of the attachment (BT-123). Example: `Stundennachweis März 2026`
`reference`	string	optional	Identifier of the supporting document (BT-122). Example: `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. Example: `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.

Field	Type	Required	Description
`exemptionCertificateNumber`	string	optional	Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a "#FREISTELLUNG#" note documenting the construction-withholding exemption. Example: `FB-2026-0042`
`withholdingPercent`	number	optional	Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented. Example: `15`
`recipientTaxOffice`	string	optional	Tax office responsible for the recipient of the construction service. Example: `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.

Field	Type	Required	Description
`countryCode`	string	required	ISO 3166-1 alpha-2 country code identifying this country-specific block. Example: `DE` If countrySpecific is set, countryCode inside it is required — even though the country code is already in the path.
`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. Example: `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. Example: `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.

The full specification

This page covers the invoice object. The full OpenAPI specification with every endpoint is available as a file — for code generators, Postman or your own editor.

Open openapi-full.json

Creator API

Generate invoices in 14 formats

Validator API

Check invoice data against the KoSIT rules

Error Handling

Error messages and what causes them

Field reference

One complete example

Three places where integrations get stuck

All fields

invoice

servicePeriod

seller

seller.identifiers[]

seller.contact

seller.bankAccount

buyer

buyer.identifiers[]

buyer.contact

buyer.bankAccount

payee

payee.identifiers[]

payee.contact

payee.bankAccount

items[]

items[].classification[]

items[].attributes[]

items[].servicePeriod

items[].discount

items[].allowances[]

items[].charges[]

taxSummary[]

paymentTerms

paymentTerms.earlyPaymentDiscount

paymentMethods[]

allowancesCharges[]

delivery

delivery.address

directDebitMandate

cardAccount

supportingDocuments[]

retention

prepayments[]

prepayments[].reference

deliveryNote

thirdPartyPayments[]

attachments[]

constructionTax

countrySpecific

The full specification

Next

Creator API

Validator API

Error Handling