XRechnung Creation API Reference

Technical reference for generating XRechnung XML invoices from a structured JSON request. Submit seller, buyer, line items and the Leitweg-ID, totals and the tax breakdown are calculated automatically. The API returns an XRechnung 3.0 CII document validated against the EN 16931 Schematron and the KoSIT CIUS rules before delivery, ready for submission to German government portals (ZRE, OZG-RE) or via the Peppol network.

POST https://api.invoicexml.com/v1/create/xrechnung

Quickstart

A minimal request, copy, paste, get a compliant invoice back.

curl -X POST https://api.invoicexml.com/v1/create/xrechnung \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o invoice-xrechnung.xml \
  -d '{
  "invoice": {
    "invoiceNumber": "INV-2025-001",
    "issueDate": "2025-07-01",
    "currency": "EUR",
    "buyerReference": "991-12345-67",
    "seller": {
      "name": "Acme GmbH",
      "vatIdentifier": "DE123456789",
      "legalRegistration": { "identifier": "HRB98765" },
      "postalAddress": {
        "line1": "Musterstr. 1",
        "city": "Berlin",
        "postCode": "10115",
        "country": "DE"
      },
      "contact": {
        "name": "Max Mustermann",
        "phone": "+49 30 12345678",
        "email": "[email protected]"
      },
      "electronicAddress": { "identifier": "[email protected]", "schemeId": "EM" }
    },
    "buyer": {
      "name": "Example Corp",
      "postalAddress": {
        "line1": "12 Rue de Rivoli",
        "city": "Paris",
        "postCode": "75001",
        "country": "FR"
      },
      "electronicAddress": { "identifier": "FR12345678901", "schemeId": "9930" }
    },
    "paymentDetails": {
      "paymentAccountIdentifier": "DE89370400440532013000"
    },
    "lines": [
      {
        "quantity": 10,
        "priceDetails": { "netPrice": 150.00 },
        "vatInformation": { "rate": 19 },
        "item": { "name": "Consulting Services" }
      }
    ]
  },
  "options": {
    "language": "en"
  }
}'

That's the whole request, the API fills in the rest.

invoice.totals and invoice.vatBreakdowns are calculated from line items.
invoice.typeCode defaults to 380 (commercial invoice), specificationId is set per standard.
The options object is optional. Every field has a sensible default, see Options below.

Try it out online, no coding required

Fill in the form and download a compliant invoice instantly, right in your browser.

Try It Online

Request body

Send invoice data as application/json. The body has two top-level keys: invoice (required) and options (optional). Browse the fields below; toggle Required only for the minimal payload, or filter by name.

POST /v1/create/xrechnung Request body

invoiceobjectrequired22 fields · 7 requiredThe invoice document. Holds all business terms and groups defined by EN 16931.

invoiceNumberstringrequiredBT-1Unique invoice identifier.

issueDatedaterequiredBT-2Date the invoice was issued, in YYYY-MM-DD format.

currencystringrequiredBT-5ISO 4217 currency code (e.g. EUR, USD, GBP).

buyerReferencestringrequiredBT-10Buyer reference. Carries the Leitweg-ID, e.g. 991-12345-67.

sellerobjectrequired10 fields · 5 requiredBG-4The party issuing the invoice.

namestringrequiredBT-27Legal business name.

vatIdentifierstringrequiredBT-31VAT identification number, including country prefix (e.g. DE123456789). At least one seller identifier (this, legalRegistration.identifier, or an identifiers[] entry) is required by EN 16931 BR-CO-26.

postalAddressobjectrequired7 fields · 3 requiredBG-5Seller's postal address.

line1stringrequiredBT-35Street address, line 1.

citystringoptionalBT-37City name.

postCodestringrequiredBT-38Postal or ZIP code.

countrystringrequiredBT-40ISO 3166-1 alpha-2 country code (e.g. DE, FR).

line2stringoptionalBT-36Address line 2.

line3stringoptionalBT-162Address line 3.

countrySubdivisionstringoptionalBT-39Region or state (e.g. Bayern).

contactobjectrequired3 fields · 3 requiredBG-6Seller contact person.

namestringrequiredBT-41Contact person's name.

phonestringrequiredBT-42Contact phone number.

emailstringrequiredBT-43Contact email address.

electronicAddressobjectrequired2 fields · 2 requiredBT-34Electronic routing endpoint, used by Peppol and similar networks.

identifierstringrequiredBT-34Endpoint identifier (email, GLN, VAT number, etc.).

schemeIdstringrequiredBT-34-1Peppol Electronic Address Scheme (EAS) code.

Allowed values

EMEmail address

9930Generic EU VAT registration number

0204German Leitweg-ID (routing identifier)

0088GS1 Global Location Number (GLN)

0184OpenPEPPOL participant identifier

9958German Umsatzsteuer-ID

0009French SIRET

0060Dun & Bradstreet (DUNS)

0190Dutch OIN

0192Norwegian Organisasjonsnummer

legalRegistrationobjectoptional2 fieldsBT-30Legal company registration (e.g. SIRET in France, HRB in Germany).

identifierstringoptionalBT-30Registration number (e.g. HRB98765). Required when legalRegistration is present.

schemeIdstringoptionalBT-30-1Scheme code for the registration number (e.g. 0002 SIRENE, 0007 Sweden Bolagsverket).

tradingNamestringoptionalBT-28Trading name, if different from the legal business name.

taxRegistrationIdentifierstringoptionalBT-32National tax registration ID, when distinct from the VAT ID.

additionalLegalInformationstringoptionalBT-33Free-text additional legal information (e.g. share capital, registration court).

identifiersobject[]optional2 fieldsBT-29Additional seller identifiers (e.g. GLN, DUNS). 0..n entries.

identifierstringoptionalBT-29Identifier value. Required when an identifiers entry is included.

schemeIdstringoptionalBT-29-1Scheme code for the identifier (e.g. 0088 GLN, 0060 DUNS).

buyerobjectrequired8 fields · 3 requiredBG-7The party receiving the invoice.

namestringrequiredBT-44Legal business name.

vatIdentifierstringoptionalBT-48Buyer VAT ID. Required for EU cross-border and reverse-charge invoices.

postalAddressobjectrequired7 fields · 3 requiredBG-8Buyer's postal address.

line1stringrequiredBT-50Street address, line 1.

citystringoptionalBT-52City name.

postCodestringrequiredBT-53Postal or ZIP code.

countrystringrequiredBT-55ISO 3166-1 alpha-2 country code.

line2stringoptionalBT-51Address line 2.

line3stringoptionalBT-163Address line 3.

countrySubdivisionstringoptionalBT-54Region or state.

electronicAddressobjectrequired2 fields · 2 requiredBT-49Electronic routing endpoint for the buyer.

identifierstringrequiredBT-49Endpoint identifier.

schemeIdstringrequiredBT-49-1Peppol EAS scheme code. See the seller electronicAddress for the full code list.

tradingNamestringoptionalBT-45Trading name, if different from the legal name.

legalRegistrationobjectoptional2 fieldsBT-47Buyer's legal company registration.

identifierstringoptionalBT-47Registration number. Required when legalRegistration is present.

schemeIdstringoptionalBT-47-1Scheme code for the registration number.

identifiersobject[]optional2 fieldsBT-46Additional buyer identifiers. 0..n entries.

identifierstringoptionalBT-46Identifier value.

schemeIdstringoptionalBT-46-1Scheme code for the identifier.

contactobjectoptional3 fieldsBG-9Buyer contact person.

namestringoptionalBT-56Contact person's name.

phonestringoptionalBT-57Contact phone number.

emailstringoptionalBT-58Contact email address.

paymentDetailsobjectoptional8 fieldsBG-16Payment instructions for the buyer. Defaults to a SEPA credit transfer.

paymentAccountIdentifierstringoptionalBT-84IBAN or other account identifier (e.g. DE89370400440532013000).

paymentMeansCodestringoptionalBT-81UNTDID 4461 payment means code. Defaults to 30.

Allowed values

30Credit transfer (default)

58SEPA credit transfer

59SEPA direct debit

54Card payment

48Bank card

10Cash

paymentMeansTextstringoptionalBT-82Free-text description of the payment means.

remittanceInformationstringoptionalBT-83Remittance reference shown on the bank transfer.

paymentAccountNamestringoptionalBT-85Account holder name.

bicstringoptionalBT-86BIC / SWIFT code.

mandateReferencestringoptionalBT-89SEPA direct debit mandate reference.

paymentTermsstringoptionalBT-20Free-text payment terms (e.g. Net 30 days).

linesobject[]required14 fields · 4 requiredBG-25Invoice line items. At least one line is required (rule BR-16). Each line is independently VAT-categorised.

quantitydecimalrequiredBT-129Invoiced quantity. Negative values are allowed, e.g. a returned item or a credit note line.

itemobjectrequired7 fields · 1 requiredBG-31The good or service being invoiced.

namestringrequiredBT-153Item name shown on the invoice.

descriptionstringoptionalBT-154Longer item description (e.g. a components list).

sellerIdentifierstringoptionalBT-155Item identifier in the seller's catalogue.

buyerIdentifierstringoptionalBT-156Item identifier in the buyer's catalogue.

countryOfOriginstringoptionalBT-159ISO 3166-1 alpha-2 country code.

standardIdentifierobjectoptional2 fieldsBT-157Standardised item identifier, e.g. GTIN.

identifierstringoptionalBT-157Identifier value (e.g. a GTIN).

schemeIdstringoptionalBT-157-1Scheme code (e.g. 0160 for GTIN).

classificationsobject[]optional3 fieldsBT-158Item classifications (UNSPSC, eClass, etc.). 0..n entries.

identifierstringoptionalBT-158Classification code value.

schemeIdstringoptionalBT-158-1Classification scheme (e.g. TST).

schemeVersionstringoptionalBT-158-2Scheme version.

priceDetailsobjectrequired5 fields · 1 requiredBG-29Per-unit pricing for this line.

netPricedecimalrequiredBT-146Net unit price, excluding VAT.

discountAmountdecimaloptionalBT-147Discount applied to the unit price.

grossPricedecimaloptionalBT-148Unit price before discount.

priceBaseQuantitydecimaloptionalBT-149Quantity the unit price refers to (e.g. price per 100 units). Defaults to 1.

priceBaseUnitstringoptionalBT-150Unit code for the base quantity (UN/ECE Rec 20).

vatInformationobjectrequired2 fields · 1 requiredBG-30VAT treatment for this line. Drives how lines are grouped into the document-level VAT breakdown.

ratedecimalrequiredBT-152VAT rate as a percentage (e.g. 19 for 19%, 0 for zero-rated).

categoryCodestringoptionalBT-151VAT category code. Defaults to S (standard rated).

Allowed values

SStandard rated

ZZero rated

EExempt from VAT

AEReverse charge

KIntra-Community supply (EU)

GExport outside the EU

ONot subject to VAT

lineIdstringoptionalBT-126Line identifier. Auto-generated as 1, 2, … when omitted.

lineNotestringoptionalBT-127Free-text note shown on the invoice line.

unitCodestringoptionalBT-130UN/ECE Rec 20 unit code. Defaults to C62 (piece).

Allowed values

C62Piece (default)

HURHour

DAYDay

KGMKilogram

MTRMetre

MTKSquare metre

LTRLitre

lineNetAmountdecimaloptionalBT-131Line total before VAT. Auto-calculated when omitted as quantity × priceDetails.netPrice, plus any line charges and minus any line allowances.

buyerOrderLineReferencestringoptionalBT-132Buyer purchase order line reference.

lineBuyerAccountingReferencestringoptionalBT-133Buyer's accounting cost-centre reference for this line.

objectIdentifierobjectoptional2 fieldsBT-128Identifier of the object this line refers to (e.g. a subscription or asset ID).

identifierstringoptionalBT-128Identifier value.

schemeIdstringoptionalBT-128-1Scheme code for the identifier.

linePeriodobjectoptional2 fieldsBG-26Service period this line covers, when different from the document-level invoicingPeriod.

startDatedateoptionalBT-134Line period start date, YYYY-MM-DD.

endDatedateoptionalBT-135Line period end date, YYYY-MM-DD.

allowancesobject[]optional5 fieldsBG-27Discounts that apply to this one line only, deducted before VAT. They inherit the line's VAT category. 0..n entries.

amountdecimaloptionalBT-136Allowance amount. Required when an allowances entry is included.

baseAmountdecimaloptionalBT-137Base amount the percentage is calculated from.

percentagedecimaloptionalBT-138Allowance as a percentage of the base amount.

reasonstringoptionalBT-139Free-text reason for the allowance.

reasonCodestringoptionalBT-140UNTDID 5189 allowance reason code.

chargesobject[]optional5 fieldsBG-28Surcharges that apply to this one line only (e.g. a per-item handling fee). They inherit the line's VAT category. For invoice-wide shipping, use the document-level charges instead. 0..n entries.

amountdecimaloptionalBT-141Charge amount. Required when a charges entry is included.

baseAmountdecimaloptionalBT-142Base amount the percentage is calculated from.

percentagedecimaloptionalBT-143Charge as a percentage of the base amount.

reasonstringoptionalBT-144Free-text reason for the charge.

reasonCodestringoptionalBT-145UNTDID 7161 charge reason code.

totalsobjectoptional10 fieldsBG-22Document totals. Every amount is computed from your lines, charges and allowances, so the whole object is optional. paidAmount and roundingAmount are inputs rather than results; set any other field to override the calculation.

paidAmountdecimaloptionalBT-113Amount already paid, e.g. a deposit, down payment or prepaid amount. Carries no VAT and is subtracted from the grand total to give the amount due. A deposit belongs here, not in the lines.

roundingAmountdecimaloptionalBT-114Rounding adjustment added to the grand total when computing the amount due.

sumOfLineNetAmountsdecimaloptionalBT-106Sum of all line net amounts.

sumOfAllowancesdecimaloptionalBT-107Sum of document-level allowances.

sumOfChargesdecimaloptionalBT-108Sum of document-level charges.

taxBasisTotalAmountdecimaloptionalBT-109Total without VAT: line nets minus allowances plus charges.

taxTotalAmountdecimaloptionalBT-110Total VAT amount across all breakdowns.

taxTotalAmountInAccountingCurrencydecimaloptionalBT-111Total VAT in the accounting currency, when taxCurrency differs from currency.

grandTotalAmountdecimaloptionalBT-112Total with VAT: tax basis plus total VAT.

duePayableAmountdecimaloptionalBT-115Amount due: grand total minus paidAmount plus roundingAmount.

vatBreakdownsobject[]optional6 fieldsBG-23VAT breakdown per category and rate. Auto-generated from lines, document charges and document allowances grouped by (categoryCode, rate). 0..n entries.

taxableAmountdecimaloptionalBT-116Net amount taxed at this category and rate.

taxAmountdecimaloptionalBT-117VAT charged on the taxable amount.

categoryCodestringoptionalBT-118VAT category for this breakdown.

Allowed values

SStandard rated

ZZero rated

EExempt from VAT

AEReverse charge

KIntra-Community supply (EU)

GExport outside the EU

ONot subject to VAT

ratedecimaloptionalBT-119VAT rate as a percentage.

exemptionReasonTextstringoptionalBT-120Reason the amount is exempt or zero-rated. Auto-filled for non-standard categories.

exemptionReasonCodestringoptionalBT-121Coded exemption reason (e.g. VATEX-EU-AE). Auto-resolved from the category.

dueDatedateoptionalBT-9Payment due date, YYYY-MM-DD. Defaults to issue date + 30 days.

typeCodestringoptionalBT-3UNTDID 1001 document type. Defaults to 380.

Allowed values

380Commercial invoice (default)

381Credit note

384Corrected invoice

389Self-billed invoice

875Partial construction invoice

876Partial final construction invoice

specificationIdstringoptionalBT-24EN 16931 specification identifier. Auto-set per standard, override only if you know what you are doing.

taxCurrencystringoptionalBT-6VAT accounting currency, if different from currency.

businessProcessTypestringoptionalBT-23Business process identifier (e.g. urn:fdc:peppol.eu:2017:poacc:billing:01:1.0).

purchaseOrderReferencestringoptionalBT-13Buyer purchase order reference.

notesstring[]optionalBT-22Free-text invoice notes. 0..n entries.

invoicingPeriodobjectoptional2 fieldsBG-14Billing or service period the whole invoice covers.

startDatedateoptionalBT-73Period start date, YYYY-MM-DD.

endDatedateoptionalBT-74Period end date, YYYY-MM-DD.

precedingInvoiceReferencesobject[]optional2 fieldsBG-3References to the invoice(s) this document amends. Expected on a credit note (381) or corrected invoice (384). 0..n entries.

referencestringoptionalBT-25Preceding invoice number. Required when an entry is included.

issueDatedateoptionalBT-26Issue date of the preceding invoice, YYYY-MM-DD.

allowancesobject[]optional7 fieldsBG-20Discounts applied to the whole invoice (e.g. a loyalty discount), deducted from the tax basis before VAT. Unlike line allowances, each carries its own VAT category and rate. 0..n entries.

amountdecimaloptionalBT-92Allowance amount. Required when an allowances entry is included.

vatCategoryCodestringoptionalBT-95VAT category the allowance is taxed under. Required when an allowances entry is included.

Allowed values

SStandard rated

ZZero rated

EExempt from VAT

AEReverse charge

KIntra-Community supply (EU)

GExport outside the EU

ONot subject to VAT

vatRatedecimaloptionalBT-96VAT rate as a percentage (e.g. 19). Required when the category is S.

baseAmountdecimaloptionalBT-93Base amount the percentage is calculated from.

percentagedecimaloptionalBT-94Allowance as a percentage of the base amount.

reasonstringoptionalBT-97Free-text reason for the allowance.

reasonCodestringoptionalBT-98UNTDID 5189 allowance reason code.

chargesobject[]optional7 fieldsBG-21Invoice-wide shipping, freight, packaging or handling fees belong here (not in the lines). Each charge is added to the tax basis and taxed at its own VAT rate. The reason becomes the label on the PDF and in the XML. 0..n entries.

amountdecimaloptionalBT-99Charge amount. Required when a charges entry is included.

vatCategoryCodestringoptionalBT-102VAT category the charge is taxed under. Required when a charges entry is included.

Allowed values

SStandard rated

ZZero rated

EExempt from VAT

AEReverse charge

KIntra-Community supply (EU)

GExport outside the EU

ONot subject to VAT

vatRatedecimaloptionalBT-103VAT rate as a percentage (e.g. 19). Required when the category is S. Usually matches the rate of the goods being shipped.

baseAmountdecimaloptionalBT-100Base amount the percentage is calculated from.

percentagedecimaloptionalBT-101Charge as a percentage of the base amount.

reasonstringoptionalBT-104Free-text reason for the charge, e.g. Shipping. Shown as the line label on the PDF.

reasonCodestringoptionalBT-105UNTDID 7161 charge reason code (e.g. FC for freight).

deliveryobjectoptional4 fieldsBG-13Delivery information, when different from the buyer's billing address.

receiverNamestringoptionalBT-70Deliver-to party name.

locationIdentifierstringoptionalBT-71Deliver-to location identifier (e.g. GLN).

actualDeliveryDatedateoptionalBT-72Actual delivery date, YYYY-MM-DD.

deliveryAddressobjectoptional7 fieldsBG-15Delivery postal address.

line1stringoptionalBT-75Street address, line 1.

citystringoptionalBT-77City name.

postCodestringoptionalBT-78Postal or ZIP code.

countrystringoptionalBT-80ISO 3166-1 alpha-2 country code.

line2stringoptionalBT-76Address line 2.

line3stringoptionalBT-165Address line 3.

countrySubdivisionstringoptionalBT-79Region or state.

optionsobjectoptional2 fieldsBehaviour switches that change how the output is built. Every field has a sensible default, so the whole object is optional.

languagestringoptionalLanguage for the rendered PDF's labels and date formatting. Defaults to en. Only affects the PDF endpoints (facturx / zugferd); the XML endpoints have no PDF, so it has no effect on their output.

Allowed values

enEnglish

deGerman

frFrench

versionstringoptionalXRechnung specification version to produce and validate against. Omitted means the version currently in force. When KoSIT announces a new version, it becomes available here during the official transition window before the default flips, and the outgoing version stays selectable until its sunset date.

Allowed values

3.0XRechnung 3.0 (currently in force, default)

Example payload all fields

Headers

Header	Value
Authorization *	Bearer YOUR_API_KEY
Content-Type	application/json

Response

200 Generated PDF

The invoice was generated. The response body is the PDF, returned as a binary download.

Content-Type: application/pdf

400 Model validation error

One or more request fields are missing or invalid, so generation never started.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errorCode": 4002,
  "valid": false,
  "detail": "The request failed validation with 1 error(s).",
  "errors": [
    {
      "rule": null,
      "line": null,
      "message": "The Name field is required.",
      "btCodes": ["BT-27"],
      "fields": ["seller.name"],
      "raw": null
    }
  ],
  "warnings": []
}

400 Schematron validation error

The request was well-formed, but the generated invoice failed EN 16931 Schematron business rules.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "XML Validation Failed",
  "status": 400,
  "detail": "The generated invoice contains 2 validation error(s).",
  "errors": [
    {
      "rule": "BR-CO-15",
      "line": null,
      "message": "The invoice total with VAT does not match. Expected 1500.00 + 285.00 = 1785.00.",
      "btCodes": ["BT-112"],
      "fields": ["totals.grandTotalAmount"],
      "raw": "[BR-CO-15] EN16931: Invoice total amount with VAT = 1785.00 expected 1500.00 + 285.00. (at /*:CrossIndustryInvoice/*:SupplyChainTradeTransaction/*:ApplicableHeaderTradeSettlement)"
    },
    {
      "rule": "BR-S-08",
      "line": null,
      "message": "The VAT breakdown for Standard rate must have a positive taxable amount and the correct rate. Check the tax breakdown.",
      "btCodes": ["BT-116", "BT-117"],
      "fields": ["taxBreakdown[0].taxableAmount"],
      "raw": "[BR-S-08] EN16931: VAT category tax amount must equal category basis × rate. (at /*:CrossIndustryInvoice/*:SupplyChainTradeTransaction/*:ApplicableHeaderTradeSettlement/*:ApplicableTradeTax)"
    }
  ],
  "warnings": [
    {
      "rule": "BR-CL-25",
      "line": null,
      "message": "The seller country code should be a valid ISO 3166-1 alpha-2 value.",
      "btCodes": ["BT-40"],
      "fields": ["seller.postalAddress.country"],
      "raw": "[BR-CL-25] EN16931: Country codes should follow ISO 3166-1 alpha-2. (at /*:CrossIndustryInvoice/*:SupplyChainTradeTransaction/*:ApplicableHeaderTradeAgreement/*:SellerTradeParty)"
    }
  ],
  "traceId": "00-54efc3135dd95c21098f45b67ae2b5ab-c894e992bbcccfd7-00",
  "errorCode": 4001
}

Error Reference

Errors are returned as RFC 7807 ProblemDetails. The errorCode field indicates the error category.

errorCode	Meaning	errors key
4001	XML validation, the generated XML violates EN 16931 Schematron rules. `errors` is a flat array of finding objects, each with `rule`, `line`, `message`, `btCodes`, `fields`, and `raw`. A parallel `warnings` array carries non-blocking advisory findings of the same shape.	errors[] warnings[]
4002	Model validation, one or more request fields are missing or invalid. Returned as the same flat `errors` array of finding objects as 4001, with `fields` pointing at the offending input.	errors[]
4000	General error, check `detail` for more information.	none

Useful resources

Companion material for integrating against the API.

Try it online

Fill in a form, no code required, and download a compliant invoice straight from your browser.

invoicexml.com/api/create/xrechnung

OpenAPI specification

The full OpenAPI 3.1 document. Drop it into Postman, Insomnia, or any code generator to scaffold a client.

api.invoicexml.com/v1/openapi

Interactive API explorer

Browse and call every endpoint directly from the browser, powered by Scalar.

api.invoicexml.com/v1/scalar

Frequently Asked Questions

Which XRechnung version is generated, and what does options.version do?

The currently effective specification version, XRechnung 3.0, declared as urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0 and validated with the matching KoSIT rules. options.version currently accepts 3.0 and can be omitted. When the announced XRechnung 4.0 gets an effective date, it becomes available here during the transition window before the default flips, and the outgoing version stays pinnable until its sunset; the full policy is on the Profiles and versions page of these docs.

Is the Leitweg-ID required?

Yes. XRechnung mandates a Leitweg-ID (routing identifier) in the invoice.buyerReference field for B2G invoicing. You must supply it in the request, the API validates its presence before generating the output.

What seller fields does XRechnung require beyond the defaults?

XRechnung requires the full seller.contact group (name, phone, email) and seller.electronicAddress for Peppol routing, in addition to seller.vatIdentifier. The request body documentation marks these as required on this page.

Can I create XRechnung in UBL syntax instead of CII?

Yes, via POST /v1/create/ubl with options.profile set to xrechnung. This endpoint always emits the CII syntax. Both syntaxes are valid XRechnung; pick the one your recipient or portal integration expects.

What is the difference between /create/xrechnung and /create/zugferd?

The /create/zugferd endpoint produces a hybrid PDF/A-3 with embedded XML, ideal for B2B exchange. The /create/xrechnung endpoint produces a standalone XML document with the stricter German CIUS rules, required for B2G submissions to government portals.

Is the output validated automatically?

Yes. Every generated XRechnung invoice is validated against the EN 16931 Schematron rules and the additional XRechnung CIUS constraints (the BR-DE rules) before delivery. If validation fails, the API returns a 400 response with errorCode 4001 and the violated rules as findings with rule id, layer, and field paths.

Where do I submit the generated XRechnung?

XRechnung invoices are typically submitted via the Peppol network or uploaded directly to the ZRE (Zentrale Rechnungseingangsplattform) or OZG-RE portals for German federal, state, and municipal authorities.

Why is the request a JSON body and not multipart/form-data?

The /create endpoints accept a nested JSON document modelled directly on the EN 16931 semantic model (business terms and groups). This keeps deep structures like postal addresses, line price details, and VAT information clean to express, and matches what most modern HTTP clients expect. Set Content-Type: application/json.