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.

147

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 Allowed values: `invoice, credit_note, proforma, correction`
`issueDate`	string	required	Issue date (ISO 8601: YYYY-MM-DD) Example: `2026-03-20`
`dueDate`	string	required	Due date (ISO 8601: YYYY-MM-DD) Example: `2026-04-19`
`deliveryDate`	string	optional	Delivery/service date (ISO 8601) Example: `2026-03-20`
`servicePeriod` See fields	object	optional	Service period (Leistungszeitraum). Required in DE if different from issueDate.
`seller` See fields	object	required	Seller party information
`buyer` See fields	object	required	Buyer party information
`items` See fields	object[]	required	Invoice line items
`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
`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`
`roundingAmount`	number	optional	Rounding amount (BT-114) Example: `0.01`
`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.
`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). Required in DE if different from issueDate.

Field	Type	Required	Description
`start`	string	required	Period start (ISO 8601: YYYY-MM-DD) Example: `2026-03-01`
`end`	string	required	Period end (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 Example: `Hauptstraße 42`
`additionalStreet`	string	optional	Additional address line Example: `2. OG, Raum 5`
`city`	string	optional	City Example: `Berlin`
`postalCode`	string	optional	Postal code 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 Example: `27/123/45678`
`vatId`	string	optional	EU VAT identification number Example: `DE136695976`
`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.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`

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 Example: `Hauptstraße 42`
`additionalStreet`	string	optional	Additional address line Example: `2. OG, Raum 5`
`city`	string	optional	City Example: `Berlin`
`postalCode`	string	optional	Postal code 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 Example: `27/123/45678`
`vatId`	string	optional	EU VAT identification number Example: `DE136695976`
`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.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`

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`

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 Example: `SVC-DEV-001`
`quantity`	number	required	Quantity (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) Example: `120`
`discount` See fields	object	optional	Line item discount (BT-136 to BT-138)
`taxRate`	number	required	Tax rate in percent 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.

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`

taxSummary[]

Field	Type	Required	Description
`taxRate`	number	required	Tax rate in percent 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`

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.

paymentTerms.earlyPaymentDiscount

Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.

Field	Type	Required	Description
`days`	number	required	Discount valid within this many days Example: `10`
`discountPercent`	number	required	Discount percentage (Skonto) Example: `2`

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)
`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	required	SEPA creditor identifier (BT-90) Example: `DE98ZZZ09999999999`
`debitAccountId`	string	optional	Debited account IBAN (BT-91) Example: `DE89370400440532013000`

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). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment). Example: `JVBERi0xLjcKJeLjz9MK...`
`description`	string	optional	Optional human-readable description of the attachment (BT-123). Example: `Stundennachweis März 2026`

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.

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 21+ formats

Validator API

Check invoice data against the KoSIT rules

Error Handling

Error messages and what causes them