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 document, in UBL syntax by default or CII via options.syntax, 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": "DE123456789", "schemeId": "9930" }
    },
    "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": {
    "syntax": "ubl",
    "validationLanguage": "de"
  }
}'

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.

Invoice language

The API fills in a few texts for you when the JSON leaves them empty: the payment terms (BT-20), stated whenever an amount is due, and the VAT exemption reason (BT-120) of reverse charge, intra-Community, export and out-of-scope breakdowns. They are written in English unless options.language says otherwise:

"options": {
  "language": "fr"
}

With fr a French invoice reads "Payable à réception de cette facture" or "Échéance le 30/09/2026", and a reverse-charge breakdown carries "Autoliquidation"; with de the German equivalents. Your own paymentTerms and exemptionReasonText always take precedence, and the option never changes codes, structure or validation.

Validation messages in German or French

When a request is rejected, every finding carries a plain-language message you can show to your users. They are written in English unless options.validationLanguage asks for German or French:

"options": {
  "validationLanguage": "de"
}

Only the message changes. rule, btCodes, fields and raw stay the same in every language, so keep matching on them. The option is independent of options.language, which sets the language of the invoice itself, and a value other than en, de or fr is rejected with a 400 (errorCode 4002). Localized error messages lists which rules have German and French wording.

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

invoiceobjectrequired26 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. Common values: 9930 (German VAT), 0204 (German Leitweg-ID), 0088 (GS1 GLN), 0192 (Norwegian Organisasjonsnummer), 9957 (French VAT). The full set is large and country-specific, so see the official EAS code list for every value.

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 seller.electronicAddress.schemeId for common values and the full EAS 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 (e.g. GLN, DUNS). 0..n entries.

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

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

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 (credit transfer). Common values: 30 (credit transfer), 58 (SEPA credit transfer), 59 (SEPA direct debit), 48 (bank card), 49 (direct debit), 10 (cash). Accepts any code from the UNTDID 4461 code list; the readable names (e.g. CreditTransfer) also work.

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.

itemobjectrequired8 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.

attributesobject[]optional2 fieldsBG-32Free-form name/value pairs describing the item, e.g. Colour = Red or a serial number. Shown on the invoice under the item. 0..n entries.

namestringoptionalBT-160Attribute name. Required when an attributes entry is included.

valuestringoptionalBT-161Attribute value. Required when an attributes entry is included.

priceDetailsobjectrequired5 fieldsBG-29Per-unit pricing for this line.

netPricedecimaloptionalBT-146Net unit price, excluding VAT. Required unless grossPrice is given, in which case it is calculated as gross price minus discountAmount.

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-of-measure code for the base quantity. Same UN/ECE Rec 20 values as unitCode.

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-of-measure code. Defaults to H87 (piece). Common values: H87 (piece), HUR (hour), DAY (day), KGM (kilogram), MTR (metre), LTR (litre). C62 (one) is accepted as well. The list runs to several hundred codes, so see the official UN/ECE Rec 20 code list for every value.

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 unless baseAmount and percentage are given, in which case it is calculated as base amount × percentage / 100.

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 unless baseAmount and percentage are given, in which case it is calculated as base amount × percentage / 100.

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). Entries with amounts replace the generated breakdown. To only add an exemption reason, send an entry without amounts, e.g. { "categoryCode": "E", "exemptionReasonText": "..." }: the breakdown is still generated and the reason goes on the matching category (and rate, if given). 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 reverse charge, intra-community, export and not subject to VAT (AE, K, G, O). Required for exempt (E), which covers many legal bases.

exemptionReasonCodestringoptionalBT-121Coded exemption reason (e.g. VATEX-EU-AE). Auto-resolved for AE, K, G and O.

dueDatedateoptionalBT-9Payment due date, YYYY-MM-DD. Never invented: when omitted, no due date is written and the payment terms (BT-20) state that the invoice is payable on receipt, unless you supply paymentDetails.paymentTerms yourself.

typeCodestringoptionalBT-3UNTDID 1001 document type. Defaults to 380. Progress and instalment invoices use 875 (construction, Abschlagsrechnung) or 326 (other trades); 386 is a request for payment before delivery. 389 is a self-billed invoice, issued by the buyer on the seller's behalf, and 261 credits one. Credit notes (381, 261) carry positive amounts and reference the original invoice in precedingInvoiceReferences. XRechnung's BR-DE-17 expects one of 326, 380, 381, 384, 389, 875, 876 or 877 and flags any other code with a warning.

Allowed values

380Commercial invoice (default)

381Credit note

384Corrected invoice

326Partial invoice

875Partial construction invoice

876Partial final construction invoice

877Final construction invoice

386Prepayment invoice

383Debit note

389Self-billed invoice

261Self-billed credit note

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.

vatPointDateCodestringoptionalBT-8UNTDID 2005 code stating when VAT becomes due.

Allowed values

3Invoice issue date

35Delivery date

432Paid to date

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

contractReferencestringoptionalBT-12Number of the contract the invoice is issued under.

purchaseOrderReferencestringoptionalBT-13Buyer purchase order reference.

despatchAdviceReferencestringoptionalBT-16Delivery note number of the shipment this invoice covers.

notes(string | object)[]optionalBT-22Invoice notes, 0..n entries. Each entry is either a plain string, or an object { "subjectCode": "PMT", "note": "..." } carrying a UNTDID 4451 subject code (BT-21). The coded form is how the French mandate's mandatory mentions travel: PMT recovery costs, PMD late-payment penalties, AAB discount terms.

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.

supportingDocumentsobject[]optional8 fieldsBG-24References to documents that substantiate the invoice (a timesheet, a purchase order copy, an annexe PDF), optionally with the file itself embedded as base64. 0..n entries.

referencestringoptionalBT-122Identifier of the supporting document. Required when a supportingDocuments entry is included.

documentTypeCodestringoptionalBT-122-0UNTDID 1001 document type code. Defaults to 916.

Allowed values

916Related document (default)

50Tender or lot reference (BT-17)

130Invoiced object identifier (BT-18)

schemeIdstringoptionalBT-18-1Identification scheme of the reference. Only meaningful for invoiced object identifiers (documentTypeCode 130).

descriptionstringoptionalBT-123Free-text description of the supporting document.

externalUristringoptionalBT-124URL where the document can be downloaded.

attachmentstringoptionalBT-125The embedded document, base64 encoded.

attachmentMimeCodestringoptionalBT-125-1MIME type of the attached document. EN 16931 allows only the listed values.

Allowed values

application/pdfPDF

image/pngPNG image

image/jpegJPEG image

text/csvCSV

application/vnd.openxmlformats-officedocument.spreadsheetml.sheetExcel spreadsheet (xlsx)

application/vnd.oasis.opendocument.spreadsheetOpenDocument spreadsheet (ods)

attachmentFilenamestringoptionalBT-125-2Filename of the attached document, e.g. timesheet-july.pdf.

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 unless baseAmount and percentage are given, in which case it is calculated as base amount × percentage / 100.

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 unless baseAmount and percentage are given, in which case it is calculated as base amount × percentage / 100.

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).

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

receiverNamestringoptionalBT-70Deliver-to party name.

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

locationIdentifierSchemeIdstringoptionalBT-71-1ISO 6523 ICD scheme of the location identifier, e.g. 0088 for a GLN or 0009 for a French SIRET.

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.

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

languagestringoptionalLanguage of the invoice. Sets the wording of the texts the API fills in for you when the JSON leaves them empty: the payment terms (BT-20) and the VAT exemption reason (BT-120) of reverse charge, intra-Community, export and out-of-scope breakdowns, for example Autoliquidation on a French invoice. Your own paymentTerms and exemptionReasonText always take precedence. Defaults to en.

Allowed values

enEnglish

deGerman

frFrench

validationLanguagestringoptionalLanguage of the validation findings when the request is rejected: the message of every entry in the errors and warnings arrays. rule, btCodes, fields and raw stay the same in every language, so match on those, never on the message text. Independent of language, which sets the language of the invoice itself. Defaults to en; any other value, regional tags such as de-DE included, is rejected with a 400 (errorCode 4002).

Allowed values

enEnglish

deGerman

frFrench

syntaxstringoptionalXML syntax of the produced XRechnung. XRechnung is one CIUS that legally exists in two interchangeable syntaxes; both declare the same specification identifier (BT-24) and pass the same KoSIT BR-DE rules before delivery, so the choice is purely about which XML dialect your receiver or archive prefers.

Allowed values

ublUBL (default)

ciiUN/CEFACT Cross Industry Invoice

Example payload all fields

Headers

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

Response

200 Generated XML

The invoice was generated and validated. The response body is the XML document, returned as a file download named invoice-xrechnung.xml with the invoice number appended.

Content-Type: application/xml

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": "BR-06",
      "layer": null,
      "line": null,
      "message": "Enter the seller name.",
      "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.

Code examples on GitHub

Runnable XRechnung integration samples in C#, Java, PHP, Python, Node.js, and browser JavaScript, ready to clone and adapt.

InvoiceXML/xrechnung-api-examples

Try it online

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

www.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?

The specification currently in force, declared with its official XRechnung CustomizationID and validated with the matching KoSIT rules. There is no version to select: when KoSIT sets an effective date for a new version, we prepare the new rule set during the transition window and switch on that date, announced ahead of time; 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 choose between the UBL and CII syntax?

Yes, with options.syntax: ubl (the default) or cii. Both syntaxes are valid XRechnung, carry the same specification identifier, and pass the same KoSIT rules; 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.

Can the generated XML be in German?

Yes. Set options.language to de and every text the API fills in for you is written in German: the payment terms (BT-20) added when an amount is due and you supply none, for example Zahlbar bei Erhalt dieser Rechnung, and the VAT exemption reason (BT-120) added to reverse charge, intra-Community, export and out-of-scope breakdowns, for example Steuerschuldnerschaft des Leistungsempfängers. Your own paymentTerms and exemptionReasonText are always used as is; the option changes no codes, structure or the BR-DE validation. English is the default, fr is available too.

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.