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