Copy page

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.