365 business E-Invoice

ZUGFeRD XML Mapping Reference

This document lists all XML node mappings used when generating ZUGFeRD 2.3 / Factur-X (Cross Industry Invoice, CII) documents from Microsoft Dynamics 365 Business Central posted sales invoices and credit memos.

The XML paths below are relative to CrossIndustryInvoice/SupplyChainTradeTransaction/ (or CrossIndustryInvoice/ExchangedDocument/ where noted). BT numbers follow EN 16931-1:2017 and the ZUGFeRD 2.3 EXTENDED profile.

Document Information (`ExchangedDocument`)

Paths are relative to CrossIndustryInvoice/ExchangedDocument/.

XML Node	BT Field	Description
`ID`	BT-1	Invoice number — Sales Invoice / Credit Memo `No.`
`TypeCode`	BT-3	Invoice type code (UNTDID 1001): `380` = Commercial Invoice, `381` = Credit Note, `386` = Prepayment Invoice
`IssueDateTime/DateTimeString`	BT-2	Invoice issue date — Sales Invoice / Credit Memo `Document Date`
`IncludedNote/Content` (SubjectCode `AAB`)	BT-22	Payment terms note — text derived from the `Payment Terms Code` of the document (language-aware)
`IncludedNote/Content` (SubjectCode `ACB`)	BT-22	Invoice pre-text — concatenated descriptions from sales lines of type blank (text lines) placed before the first item line
`IncludedNote/Content` (SubjectCode `REG`)	BT-22	Seller company information block written for regulatory (Impressum) purposes; contains seller name, address, GLN (if enabled), and Leitweg-ID (if set)

Trade Agreement (`ApplicableHeaderTradeAgreement`)

Paths are relative to SupplyChainTradeTransaction/ApplicableHeaderTradeAgreement/.

XML Node	BT Field	Description
`BuyerReference`	BT-10	Buyer routing reference — Sales Invoice `External Document No.` (used as the buyer's internal routing reference, e.g. Leitweg-ID of the buyer; omitted when blank)
`SellerTradeParty/ID`	BT-29	Seller identifier — Company Information `GLN` (only written when Use GLN in Electronic Document is enabled on Company Information)
`SellerTradeParty/GlobalID[@schemeID='0088']`	BT-29	Seller global identifier (GLN, scheme code 0088) — Company Information `GLN` (only written when Use GLN in Electronic Document is enabled)
`SellerTradeParty/Name`	BT-27	Seller name — Company Information `Name` + `Name 2` (or the Responsibility Center name if one is assigned to the document)
`SellerTradeParty/DefinedTradeContact/PersonName`	BT-41	Seller contact person name — `Salesperson/Purchaser` record `Name` for the salesperson assigned to the document
`SellerTradeParty/DefinedTradeContact/TelephoneUniversalCommunication/CompleteNumber`	BT-42	Seller contact telephone — `Salesperson/Purchaser` `Phone No.` (omitted when blank)
`SellerTradeParty/DefinedTradeContact/EmailURIUniversalCommunication/URIID`	BT-43	Seller contact email address — `Salesperson/Purchaser` `E-Mail` (omitted when blank)
`SellerTradeParty/PostalTradeAddress/PostcodeCode`	BT-38	Seller post code — Company Information / Responsibility Center `Post Code`
`SellerTradeParty/PostalTradeAddress/LineOne`	BT-35	Seller address line 1 — Company Information / Responsibility Center `Address`
`SellerTradeParty/PostalTradeAddress/LineTwo`	BT-36	Seller address line 2 — Company Information / Responsibility Center `Address 2` (omitted when blank)
`SellerTradeParty/PostalTradeAddress/LineThree`	BT-162	Seller address line 3 — available via integration event; not populated from standard BC fields
`SellerTradeParty/PostalTradeAddress/CityName`	BT-37	Seller city — Company Information / Responsibility Center `City`
`SellerTradeParty/PostalTradeAddress/CountryID`	BT-40	Seller country code (ISO 3166-1 alpha-2) — Company Information / Responsibility Center `Country/Region Code`
`SellerTradeParty/SpecifiedTaxRegistration/ID[@schemeID='VA']`	BT-31	Seller VAT identifier — Company Information `VAT Registration No.` (omitted when blank)
`SellerTradeParty/SpecifiedTaxRegistration/ID[@schemeID='FC']`	BT-32	Seller tax registration identifier — Company Information `Registration No.` (omitted when blank)
`BuyerTradeParty/ID`	BT-46	Buyer identifier — Service Participant ID of the customer (`E-Document Service Participant`); falls back to Customer `GLN` when no routing ID is present and GLN is enabled
`BuyerTradeParty/GlobalID[@schemeID='0088']`	BT-56	Buyer global identifier (GLN, scheme code 0088) — Customer `GLN` (only written when Use GLN in Electronic Document is enabled on the customer record)
`BuyerTradeParty/Name`	BT-44	Buyer name — Sales Invoice / Credit Memo `Bill-to Name` + `Bill-to Name 2`
`BuyerTradeParty/PostalTradeAddress/PostcodeCode`	BT-53	Buyer post code — Sales Invoice / Credit Memo `Bill-to Post Code`
`BuyerTradeParty/PostalTradeAddress/LineOne`	BT-50	Buyer address line 1 — Sales Invoice / Credit Memo `Bill-to Address`
`BuyerTradeParty/PostalTradeAddress/LineTwo`	BT-51	Buyer address line 2 — Sales Invoice / Credit Memo `Bill-to Address 2` (omitted when blank)
`BuyerTradeParty/PostalTradeAddress/LineThree`	BT-163	Buyer address line 3 — available via integration event; not populated from standard BC fields
`BuyerTradeParty/PostalTradeAddress/CityName`	BT-52	Buyer city — Sales Invoice / Credit Memo `Bill-to City`
`BuyerTradeParty/PostalTradeAddress/CountryID`	BT-55	Buyer country code (ISO 3166-1 alpha-2) — Sales Invoice / Credit Memo `Bill-to Country/Region Code`
`BuyerOrderReferencedDocument/IssuerAssignedID`	BT-13	Purchase order reference — Sales Invoice `External Document No.` (the customer's purchase order number)

Trade Delivery (`ApplicableHeaderTradeDelivery`)

Paths are relative to SupplyChainTradeTransaction/ApplicableHeaderTradeDelivery/.

XML Node	BT Field	Description
`ShipToTradeParty/Name`	BT-70	Deliver-to party name — Sales Invoice / Credit Memo `Ship-to Name` + `Ship-to Name 2`
`ShipToTradeParty/PostalTradeAddress/PostcodeCode`	BT-78	Deliver-to post code — Sales Invoice / Credit Memo `Ship-to Post Code`
`ShipToTradeParty/PostalTradeAddress/LineOne`	BT-75	Deliver-to address line 1 — Sales Invoice / Credit Memo `Ship-to Address`
`ShipToTradeParty/PostalTradeAddress/LineTwo`	BT-76	Deliver-to address line 2 — Sales Invoice / Credit Memo `Ship-to Address 2` (omitted when blank)
`ShipToTradeParty/PostalTradeAddress/LineThree`	BT-165	Deliver-to address line 3 — available via integration event; not populated from standard BC fields
`ShipToTradeParty/PostalTradeAddress/CityName`	BT-77	Deliver-to city — Sales Invoice / Credit Memo `Ship-to City`
`ShipToTradeParty/PostalTradeAddress/CountryID`	BT-80	Deliver-to country code (ISO 3166-1 alpha-2) — Sales Invoice / Credit Memo `Ship-to Country/Region Code`
`ActualDeliverySupplyChainEvent/OccurrenceDateTime/DateTimeString`	BT-72	Actual delivery / shipment date — Sales Invoice / Credit Memo `Shipment Date` (omitted when blank)

Trade Settlement (`ApplicableHeaderTradeSettlement`)

Paths are relative to SupplyChainTradeTransaction/ApplicableHeaderTradeSettlement/.

Currency & Payment Means

XML Node	BT Field	Description
`InvoiceCurrencyCode`	BT-5	Invoice currency code (ISO 4217) — Sales Invoice `Currency Code`; defaults to the LCY code from General Ledger Setup when no foreign currency is used
`SpecifiedTradeSettlementPaymentMeans/TypeCode`	BT-81	Payment means type code (UNTDID 4461) — read from `Payment Method` record field bdev.EInv ZUGFeRD Pmt. Method; defaults to `58` (SEPA Credit Transfer / BankTransfer) when not configured
`SpecifiedTradeSettlementPaymentMeans/PayeePartyCreditorFinancialAccount/IBANID`	BT-84	Payment account IBAN — Bank Account `IBAN` identified by the Company Bank Account Code on the document; falls back to Company Information `IBAN` when no specific bank account is set
`SpecifiedTradeSettlementPaymentMeans/PayeePartyCreditorFinancialAccount/AccountName`	BT-85	Payment account name — Company Information `Name`
`SpecifiedTradeSettlementPaymentMeans/PayeeSpecifiedCreditorFinancialInstitution/BICID`	BT-86	Payment service provider BIC/SWIFT — Bank Account `SWIFT Code`; falls back to Company Information `SWIFT Code`

Billing Period

XML Node	BT Field	Description
`BillingSpecifiedPeriod/StartDateTime/DateTimeString`	BT-73	Invoice period start date — Header Model `BillingPeriodFrom` (omitted when not set; must be populated via integration event)
`BillingSpecifiedPeriod/EndDateTime/DateTimeString`	BT-74	Invoice period end date — Header Model `BillingPeriodTo` (omitted when not set; must be populated via integration event)

Document-Level Allowances and Charges (BG-20 / BG-21)

Sourced from posted sales lines of type Charge (Item). A negative Amount produces an allowance (ChargeIndicator = false); a positive Amount produces a charge (ChargeIndicator = true).

XML Node	BT Field	Description
`SpecifiedTradeAllowanceCharge/ChargeIndicator/Indicator`	BT-92 / BT-99	Charge or allowance indicator — `false` for document-level allowance (BG-20), `true` for document-level charge (BG-21)
`SpecifiedTradeAllowanceCharge/ActualAmount`	BT-92 / BT-99	Allowance / charge amount (absolute value) — Sales Line `Amount` (absolute) for lines of type Charge (Item)
`SpecifiedTradeAllowanceCharge/Reason`	BT-97 / BT-104	Allowance / charge reason text — Sales Line `Description`
`SpecifiedTradeAllowanceCharge/CategoryTradeTax/TypeCode`	—	Tax type code — always `VAT`
`SpecifiedTradeAllowanceCharge/CategoryTradeTax/CategoryCode`	BT-95 / BT-102	VAT category code — VAT Posting Setup `Tax Category` for the sales line
`SpecifiedTradeAllowanceCharge/CategoryTradeTax/RateApplicablePercent`	BT-96 / BT-103	VAT rate — Sales Line `VAT %`

VAT Breakdown (BG-23)

One group per unique combination of VAT category code and rate, aggregated from all invoice lines.

XML Node	BT Field	Description
`ApplicableTradeTax/CalculatedAmount`	BT-117	VAT category tax amount — sum of `VAT Amount` for the VAT group
`ApplicableTradeTax/TypeCode`	—	Tax type code — always `VAT`
`ApplicableTradeTax/BasisAmount`	BT-116	VAT category taxable amount — sum of `VAT Base` for the VAT group
`ApplicableTradeTax/CategoryCode`	BT-118	VAT category code — from the VAT Amount Line `Tax Category`
`ApplicableTradeTax/ExemptionReasonCode`	BT-121	VAT exemption reason code — VAT Posting Setup field bdev.EInv ZUGFeRD TaxCatReason (omitted when blank)
`ApplicableTradeTax/RateApplicablePercent`	BT-119	VAT category rate — `VAT %` for the VAT group

Payment Terms

XML Node	BT Field	Description
`SpecifiedTradePaymentTerms/Description`	BT-20	Payment terms description — text generated from the `Payment Terms Code` (language-aware)
`SpecifiedTradePaymentTerms/DueDateDateTime/DateTimeString`	BT-9	Payment due date — Sales Invoice / Credit Memo `Due Date` (always written; output is `00000000` when the date is not set)
`SpecifiedTradePaymentTerms/ApplicableTradePaymentDiscountTerms/BasisPeriodMeasure[@unitCode='DAY']`	—	Cash discount period in days — derived from `Payment Terms` record field `Discount Date Calculation` (converted to number of days; omitted when no discount applies)
`SpecifiedTradePaymentTerms/ApplicableTradePaymentDiscountTerms/CalculationPercent`	—	Cash discount percentage — Sales Invoice `Payment Discount %` (omitted when zero)

Monetary Summation (BG-22)

XML Node	BT Field	Description
`SpecifiedTradeSettlementHeaderMonetarySummation/LineTotalAmount`	BT-106	Sum of invoice line net amounts
`SpecifiedTradeSettlementHeaderMonetarySummation/ChargeTotalAmount`	BT-108	Sum of document-level charges
`SpecifiedTradeSettlementHeaderMonetarySummation/AllowanceTotalAmount`	BT-107	Sum of document-level allowances
`SpecifiedTradeSettlementHeaderMonetarySummation/TaxBasisTotalAmount`	BT-109	Invoice total amount without VAT
`SpecifiedTradeSettlementHeaderMonetarySummation/TaxTotalAmount[@currencyID]`	BT-110	Invoice total VAT amount in invoice currency
`SpecifiedTradeSettlementHeaderMonetarySummation/GrandTotalAmount`	BT-112	Invoice total amount with VAT
`SpecifiedTradeSettlementHeaderMonetarySummation/DuePayableAmount`	BT-115	Amount due for payment

Invoice Lines (`IncludedSupplyChainTradeLineItem`)

Paths are relative to SupplyChainTradeTransaction/IncludedSupplyChainTradeLineItem/. One element per posted sales line. Lines of type Charge (Item) and lines with zero quantity are excluded (charges are handled as document-level allowances/charges).

Line Identification

XML Node	BT Field	Description
`AssociatedDocumentLineDocument/LineID`	BT-126	Invoice line identifier — Sales Line `Line No.`

Product / Item Information (BG-31)

XML Node	BT Field	Description
`SpecifiedTradeProduct/SellerAssignedID`	BT-155	Seller's item identifier — Sales Line `No.` (item or resource number; omitted for G/L Account lines and when blank)
`SpecifiedTradeProduct/BuyerAssignedID`	BT-156	Buyer's item identifier — Sales Line `Item Reference No.` when the reference type is Customer (omitted otherwise)
`SpecifiedTradeProduct/GlobalID[@schemeID='0160']`	BT-157	Item standard identifier (GTIN, scheme code 0160) — Item `GTIN` (omitted when blank)
`SpecifiedTradeProduct/Name`	BT-153	Item name — Sales Line `Description`
`SpecifiedTradeProduct/Description`	BT-154	Item description — concatenated descriptions from blank-type (text) sales lines that immediately follow this line, up to the next non-text line or first empty line (omitted when no text lines are present)
`SpecifiedTradeProduct/OriginTradeCountry/ID`	BT-159	Item country of origin (ISO 3166-1 alpha-2) — Item `Country/Region of Origin Code` (omitted when blank)

Line Price (BG-29)

XML Node	BT Field	Description
`SpecifiedLineTradeAgreement/NetPriceProductTradePrice/ChargeAmount`	BT-146	Item net price — Sales Line `Unit Price` (net of VAT; automatically converted from gross when Prices Including VAT is enabled on the sales document)

Line Delivery (BG-25 — quantity)

XML Node	BT Field	Description
`SpecifiedLineTradeDelivery/BilledQuantity`	BT-129	Billed quantity — Sales Line `Quantity`
`SpecifiedLineTradeDelivery/BilledQuantity/@unitCode`	BT-130	Unit of measure code (UN/ECE Recommendation 20) — mapped from Sales Line `Unit of Measure Code` via the `International Standard Code` on the Unit of Measure record; defaults to `EA` (each) when not set

Line Settlement

Line VAT Information (BG-30)

XML Node	BT Field	Description
`SpecifiedLineTradeSettlement/ApplicableTradeTax/TypeCode`	—	Tax type code — always `VAT`
`SpecifiedLineTradeSettlement/ApplicableTradeTax/CategoryCode`	BT-151	Invoiced item VAT category code — VAT Posting Setup `Tax Category`; defaults to `S` (standard rate) when blank
`SpecifiedLineTradeSettlement/ApplicableTradeTax/ExemptionReasonCode`	BT-164	Tax exemption reason code — VAT Posting Setup field bdev.EInv ZUGFeRD TaxCatReason (omitted when blank)
`SpecifiedLineTradeSettlement/ApplicableTradeTax/RateApplicablePercent`	BT-152	Invoiced item VAT rate — Sales Line `VAT %`

Line Billing Period

Note: BT-134 / BT-135 fields exist in the internal Line Model and import XPath definitions, but are not written to XML during export by the current implementation. They are import-only fields.

XML Node	BT Field	Description
`SpecifiedLineTradeSettlement/BillingSpecifiedPeriod/StartDateTime/DateTimeString`	BT-134	Invoice line period start date — Line Model `BillingPeriodFrom` (import only; not exported)
`SpecifiedLineTradeSettlement/BillingSpecifiedPeriod/EndDateTime/DateTimeString`	BT-135	Invoice line period end date — Line Model `BillingPeriodTo` (import only; not exported)

Line Allowances (BG-27)

Line discounts are written as line-level allowances (ChargeIndicator = false). Both a line discount and an invoice discount can be written for the same line.

XML Node	BT Field	Description
`SpecifiedLineTradeSettlement/SpecifiedTradeAllowanceCharge/ChargeIndicator/Indicator`	—	Allowance indicator — always `false` (line-level allowance)
`SpecifiedLineTradeSettlement/SpecifiedTradeAllowanceCharge/BasisAmount`	BT-137	Invoice line allowance base amount — Sales Line `Line Discount Amount`
`SpecifiedLineTradeSettlement/SpecifiedTradeAllowanceCharge/ActualAmount`	BT-136	Invoice line allowance amount — Sales Line `Line Discount Amount` (line discount) or `Inv. Discount Amount` (invoice discount)
`SpecifiedLineTradeSettlement/SpecifiedTradeAllowanceCharge/Reason`	BT-139	Invoice line allowance reason — `Line Discount` or `Invoice Discount` (translated label)

Line Net Amount

XML Node	BT Field	Description
`SpecifiedLineTradeSettlement/SpecifiedTradeSettlementLineMonetarySummation/LineTotalAmount`	BT-131	Invoice line net amount — Sales Line `Amount` (net of VAT and discounts)

Notes

BT-39 / BT-54 (County/State): The seller county (Company Information / Responsibility Center "County") and buyer county (Bill-to County) are stored in the internal model but are not written to the XML output. CountrySubDivisionName is omitted from all PostalTradeAddress elements.
BT-29 / GLN: When Use GLN in Electronic Document is disabled on Company Information, neither SellerTradeParty/ID nor SellerTradeParty/GlobalID is written. The Seller Leitweg-ID (BT-29) field exists in the model but is not yet sourced from a standard BC field (planned extension).
BT-10 / BuyerReference: The BuyerReference element receives the Sales Invoice External Document No.. The same value is also written to BuyerOrderReferencedDocument/IssuerAssignedID (BT-13). The buyer's routing identifier (Service Participant ID / Leitweg-ID) is written to BuyerTradeParty/ID (BT-46).
BT-48 (Buyer VAT identifier): The buyer's VAT Registration No. is stored in the internal model (BuyerVATRegistrationNo) but is not written to the XML output (BuyerTradeParty/SpecifiedTaxRegistration is omitted).
Integration events: The model exposes OnBeforeInsertSalesInvoiceCrMemoHeaderToModel and OnBeforeInsertSalesInvoiceCrMemoLineToModel integration events that allow partner extensions to populate or override any model field before the XML is generated.
Profile identifier: The ExchangedDocumentContext/GuidelineSpecifiedDocumentContextParameter/ID element is hardcoded to urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended (ZUGFeRD 2.3 EXTENDED / Factur-X 1.0 EXTENDED profile). This value is not user-configurable.

Last modified on May 26, 2026

Supported Document Types Import Assistant