Invoice JSON schema: build a valid request

Use the explorer below as the request contract. It shows the complete payload, which fields are required, and the fields nested inside every object. You do not need to understand the underlying invoicing standard before building a request.

1
Find the field

Search by its JSON name, path, type, or description.

2
Open nested objects

Expand an object or array to inspect its child fields in place.

3
Let the engine calculate

AUTO mode derives line amounts, totals, and tax amounts.

Request structure

Every request has two top-level objects:

  • invoice contains the invoice number, parties, payment information, taxes, totals, and line items.
  • config selects the output syntax, specification, version, and profile.

The same InvoiceRequestDto body is accepted by the XRechnung generation API, EN 16931 generation API, and ZUGFeRD generation API.

The explorer below is split per generation endpoint. A field's required flag can differ between specs — for example buyerReference (BT-10) is required under XRechnung (enforced by the BR-DE-15 Schematron rule) but optional under EN 16931 and ZUGFeRD. Fields whose requiredness differs across specs carry a Differs across specs indicator so you know the difference is intentional, not an inconsistency. Pick the explorer for the endpoint you are calling.

The example beside each explorer contains every documented field. Hover or focus a field to locate it in the JSON, and open object fields to inspect their nested structure. Fields marked Engine calculated can be omitted in AUTO mode.

Explore the contract

InvoiceRequestDto fields

198 of 198 fields shown

invoiceobjectrequiredInvoice · BG-1 · 34 fields · 10 required

The EN 16931 invoice payload.

Constraint: The object must be present and satisfy its nested requirements.
invoiceNumberstringrequired BT-1

Unique invoice identifier.

Example: "INV-2026-001"Constraint: Provide a non-blank string.
issueDatedaterequired BT-2

ISO-8601 invoice issue date.

Example: "2026-08-17"Constraint: Use an ISO-8601 date in YYYY-MM-DD format.
invoiceTypeCodestringrequired BT-3

UNTDID 1001 type; 380 is a commercial invoice.

Example: "380"Constraint: Provide a non-blank string.
currencyCodestringrequired BT-5

ISO 4217 invoice currency.

Example: "EUR"Constraint: Provide a non-blank string.
sellerobjectrequired BG-4 Seller · BG-4 · 10 fields · 1 required

Party issuing the invoice.

Constraint: The object must be present and satisfy its nested requirements.
namestringrequired BT-27

Seller name.

Example: "Acme GmbH"Constraint: Provide a non-blank string.
tradingNamestringoptional BT-28

Additional trading name.

identifierstringoptional BT-29

Seller identifier.

legalRegistrationIdentifierstringoptional BT-30

Company-register identifier.

vatIdentifierstringoptional BT-31

VAT identifier.

taxRegistrationIdentifierstringoptional BT-32

Tax registration identifier.

electronicAddressstringoptional BT-34

Electronic routing address.

electronicAddressSchemeIdstringoptional BT-34 scheme

Electronic address scheme.

postalAddressobjectoptional BG-5 Seller postal address · BG-5 · 7 fields · 3 required

Seller postal address.

contactobjectoptional BG-6 Seller contact · BG-6 · 3 fields · 1 required

Seller contact.

buyerobjectrequired BG-7 Buyer · BG-7 · 9 fields · 1 required

Party receiving the invoice.

Constraint: The object must be present and satisfy its nested requirements.
namestringrequired BT-44

Buyer name.

Example: "Example AG"Constraint: Provide a non-blank string.
tradingNamestringoptional BT-45

Buyer trading name.

identifierstringoptional BT-46

Buyer identifier.

legalRegistrationIdentifierstringoptional BT-47

Company-register identifier.

vatIdentifierstringoptional BT-48

Buyer VAT identifier.

electronicAddressstringoptional BT-50

Electronic routing address.

electronicAddressSchemeIdstringoptional BT-50 scheme

Electronic address scheme.

postalAddressobjectoptional BG-8 Buyer postal address · BG-8 · 7 fields · 3 required

Buyer postal address.

contactobjectoptional BG-9 Buyer contact · BG-9 · 3 fields · 0 required

Buyer contact.

paymentInstructionsobjectrequired BG-16 Payment instructions · BG-16 · 6 fields · 1 required

How the invoice should be paid.

Constraint: The object must be present and satisfy its nested requirements.
meansCodestringrequired BT-81

UNCL 4461 payment means code.

Example: "58"Constraint: Provide a non-blank string.
meansTextstringoptional BT-82

Payment means text.

remittanceInformationstringoptional BT-83

Payment reference.

creditTransferobjectoptional BG-17 Credit transfer · BG-17 · 3 fields · 1 required

Credit-transfer details.

paymentCardInformationobjectoptional BG-18 Payment card · BG-18 · 2 fields · 0 required

Payment-card details.

directDebitobjectoptional BG-19 Direct debit · BG-19 · 3 fields · 1 required

Direct-debit details.

documentTotalsobjectrequired BG-22 Document totals · BG-22 · 8 fields · 0 required

Required totals container; values are calculated in AUTO mode.

Constraint: The object must be present and satisfy its nested requirements. Engine calculated
lineExtensionAmountnumberoptional BT-106

Sum of line net amounts.

Constraint: Use a finite JSON number, without a currency or percent symbol. Engine calculated
allowanceTotalAmountnumberoptional BT-107

Sum of document allowances.

Constraint: Use a finite JSON number, without a currency or percent symbol. Engine calculated
chargeTotalAmountnumberoptional BT-108

Sum of document charges.

Constraint: Use a finite JSON number, without a currency or percent symbol. Engine calculated
taxExclusiveAmountnumberoptional BT-109

Total without VAT.

Constraint: Use a finite JSON number, without a currency or percent symbol. Engine calculated
taxInclusiveAmountnumberoptional BT-112

Total with VAT.

Constraint: Use a finite JSON number, without a currency or percent symbol. Engine calculated
prepaidAmountnumberoptional BT-113

Amount already paid.

Constraint: Use a finite JSON number, without a currency or percent symbol. Engine calculated
payableRoundingAmountnumberoptional BT-114

Rounding adjustment.

Constraint: Use a finite JSON number, without a currency or percent symbol. Engine calculated
payableAmountnumberoptional BT-115

Final amount due.

Constraint: Use a finite JSON number, without a currency or percent symbol. Engine calculated
vatBreakdownsobject[]required BG-23 VAT breakdown · BG-23 · 6 fields · 2 required

One or more VAT category/rate entries.

Constraint: Provide an array containing at least one valid object.
vatCategoryTaxableAmountnumberoptional BT-116

Taxable amount.

Constraint: Use a finite JSON number, without a currency or percent symbol. Engine calculated
vatCategoryTaxAmountnumberoptional BT-117

VAT amount.

Constraint: Use a finite JSON number, without a currency or percent symbol. Engine calculated
vatCategoryCodestringrequired BT-118

S, Z, E, AE, K, G, or O.

Example: "S"Constraint: Provide a non-blank string.
vatCategoryRatenumberrequired BT-119

VAT percentage.

Example: 19Constraint: Use a finite JSON number, without a currency or percent symbol.
exemptionReasonstringoptional BT-120

Exemption reason text.

exemptionReasonCodestringoptional BT-121

Coded exemption reason.

invoiceLinesobject[]required BG-25 Invoice lines · BG-25 · 13 fields · 2 required

One or more billed line items.

Constraint: Provide an array containing at least one valid object.
lineIdentifierstringrequired BT-126

Unique line identifier.

Example: "1"Constraint: Provide a non-blank string.
notestringoptional BT-127

Line note.

quantitynumberoptional BT-129

Billed quantity; required outside MANUAL mode.

Example: 10Constraint: Use a finite JSON number, without a currency or percent symbol.
unitCodestringoptional BT-130

UNECE unit code.

Example: "C62"
netAmountnumberoptional BT-131

Line net amount.

Constraint: Use a finite JSON number, without a currency or percent symbol. Engine calculated
referencedPurchaseOrderLinestringoptional BT-132

Purchase-order line reference.

buyerAccountingReferencestringoptional BT-133

Buyer accounting code.

invoiceLinePeriodobjectoptional BG-26 Invoice-line period · BG-26 · 2 fields · 0 required

Line service period.

invoiceLineAllowancesobject[]optional BG-27 Line-level allowances · BG-27 · 5 fields · 0 required

Line discounts.

invoiceLineChargesobject[]optional BG-28 Line-level charges · BG-28 · 5 fields · 0 required

Line charges.

priceDetailsobjectoptional BG-29 Price details · BG-29 · 4 fields · 0 required

Unit pricing.

lineVatInformationobjectoptional BG-30 Line VAT information · BG-30 · 2 fields · 2 required

Line VAT category and rate.

itemInformationobjectrequired BG-31 Item information · BG-31 · 8 fields · 1 required

Product or service identity.

Constraint: The object must be present and satisfy its nested requirements.
namestringrequired BT-153

Item name.

Example: "Consulting services"Constraint: Provide a non-blank string.
descriptionstringoptional BT-154

Item description.

sellersIdentifierstringoptional BT-155

Seller-assigned identifier.

buyersIdentifierstringoptional BT-156

Buyer-assigned identifier.

standardIdentifierstringoptional BT-157

Standard identifier such as GTIN.

classifiedIdentifierstringoptional BT-158

Commodity classification.

countryOfOriginstringoptional BT-159

ISO country of origin.

itemAttributesobject[]optional BG-32 Item attributes · BG-32 · 2 fields · 0 required

Additional name/value properties.

invoiceSubTypestringoptional BT-7

Invoice sub-type code.

valueAddedTaxPointDatedateoptional BT-7/8

VAT accounting date.

Constraint: Use an ISO-8601 date in YYYY-MM-DD format.
invoiceCurrencyCodestringoptional BT-5a

VAT accounting currency code alias.

vatAccountingCurrencyCodestringoptional BT-6

VAT accounting currency.

buyerReferencestringoptionalDiffers across specs BT-10

Buyer's accounting reference.

projectReferencestringoptional BT-11

Project identifier.

contractReferencestringoptional BT-12

Contract identifier.

purchaseOrderReferencestringoptional BT-13

Purchase-order reference.

salesOrderReferencestringoptional BT-14

Sales-order reference.

despatchAdviceReferencestringoptional BT-15

Despatch advice reference.

receivingAdviceReferencestringoptional BT-16

Receiving advice reference.

tenderOrLotReferencestringoptional BT-17

Tender or lot reference.

invoicedObjectIdentifierstringoptional BT-18

Identifier of the invoiced object.

paymentTermsstringoptional BT-20

Human-readable payment terms.

invoiceNotestringoptional BT-22

Free-text invoice note.

processControlobjectoptional BG-2 Process control · BG-2 · 2 fields · 0 required

Business-process and specification identifiers.

precedingInvoiceReferenceobjectoptional BG-3 Preceding invoice reference · BG-3 · 2 fields · 1 required

Original invoice for a correction or credit note.

payeeobjectoptional BG-10 Payee · BG-10 · 3 fields · 1 required

Payment recipient when different from seller.

sellerTaxRepresentativePartyobjectoptional BG-11 Seller tax representative · BG-11 · 3 fields · 1 required

Seller's tax representative.

deliveryInformationobjectoptional BG-13 Delivery information · BG-13 · 4 fields · 0 required

Delivery party, location, date, and address.

invoicingPeriodobjectoptional BG-14 Invoicing period · BG-14 · 2 fields · 0 required

Period covered by the invoice.

documentLevelAllowancesobject[]optional BG-20 Document-level allowances · BG-20 · 7 fields · 0 required

Invoice-wide discounts.

documentLevelChargesobject[]optional BG-21 Document-level charges · BG-21 · 7 fields · 0 required

Invoice-wide charges.

additionalSupportingDocumentsobject[]optional BG-24 Additional supporting documents · BG-24 · 5 fields · 0 required

Document references, links, or base64 attachments.

configobjectrequiredGeneration config · 5 fields · 1 required

Generation standard, syntax, version, and profile.

Constraint: The object must be present and satisfy its nested requirements.
specstringoptional

Specification key such as xrechnung or EN16931; defaults from the endpoint.

Example: "xrechnung"
syntaxstringrequired

XML syntax; CII or UBL, case-insensitive.

Example: "CII"Constraint: Provide a non-blank string.
versionstringoptional

Version; omitted values resolve to the active default.

Example: "3.0.2"
profilestringoptional

Optional CIUS or profile identifier.

Example: "EN16931"
metadataLanguagestringoptional

PDF-only language for the engine-authored PDF chrome (labels, headers, footer, date format). Accepted only on the ZUGFeRD endpoint (rejected with 400 INVALID_INPUT on XRechnung and EN 16931). ISO 639-1 code, case-insensitive ("en" or "de"). Defaults to "en". The engine does not translate user-supplied invoice content.

Example: "de"

How nested requirements work

A field marked required must always be present. Optional objects can be omitted entirely, but some have required children once you include them. For example, seller.postalAddress is optional; if you include it, provide addressLine1, city, and countryCode.

Dates use YYYY-MM-DD, money and rates are JSON numbers, and country and currency values use their two-letter ISO 3166-1 and three-letter ISO 4217 codes. VAT categories use EN 16931 codes such as S (standard rated), Z (zero rated), and E (exempt).

Code values: config.metadataLanguage

config.metadataLanguage is a PDF-only option accepted solely by the ZUGFeRD generation API. It selects the language of the engine-authored PDF chrome — labels, headers, footer, and date format — not the user-supplied invoice content.

ValueMeaningNotes
enEnglish labels (default)Used when the field is omitted.
deGerman labels and date formatCase-insensitive: DE, De, de are all accepted.
  • Case-insensitive: the engine normalises the code before matching, so "DE", "De", and "de" are equivalent.
  • Default: en. Omit the field to keep English PDF chrome.
  • PDF-only restriction: sending config.metadataLanguage on the XRechnung or EN 16931 XML generation endpoints is rejected with 400 INVALID_INPUT.
  • Unsupported codes (e.g. "fr", "de-DE") are rejected with 400 INVALID_INPUT on the ZUGFeRD endpoint. Only bare ISO 639-1 codes en and de are accepted.
  • The engine does not translate user-supplied invoice content (line descriptions, party names, payment terms). metadataLanguage affects only the engine-authored PDF presentation layer.