Shopify to ZUGFeRD 2.3 (EN 16931 / Extended) Integration & Schema Crosswalk
Why Native Shopify Orders Fail German ZUGFeRD 2.3 Validation
Shopify's `orders/create` and `orders/paid` JSON payloads omit critical EN 16931 Business Terms required by the German **E-Rechnung (§ 14 UStG)** mandate:
1. **Missing UN/CEFACT Unit Codes (BT-130):** Shopify line items lack ISO/UNECE Rec 20 unit codes (e.g. `C62` for pieces/units).
2. **Gross vs. Net Rounding Drift (BR-CO-10):** When `taxes_included: true` is active in Shopify, back-calculating net unit prices causes 0.01 EUR drift between `BT-106` and `BT-116`.
3. **Buyer Tax ID & Leitweg-ID Storage:** Shopify stores B2B VAT IDs in `customer.tax_exemptions` or `note_attributes`, which must be mapped to `ram:BuyerTradeParty/ram:SpecifiedTaxRegistration`.
Mandatory Shopify to ZUGFeRD 2.3 (EN 16931 / Extended) Field Crosswalk Matrix
Deterministic attribute mapping from Shopify payloads to EN 16931 Business Terms (BT) and CII-D16B XPaths.
| Shopify Source Field | EN 16931 Business Term | Target CII-D16B XPath | Card. | Transformation & Normalization Rule | Schematron Rule |
|---|---|---|---|---|---|
| order.name string ("#1042") | BT-1 (Invoice Number) | /rsm:CrossIndustryInvoice/rsm:ExchangedDocument/ram:ID | 1..1 | Strip leading "#" if required by accounting sequence | BR-02 ↗ |
| order.created_at ISO-8601 Timestamp | BT-2 (Issue Date) | /rsm:CrossIndustryInvoice/rsm:ExchangedDocument/ram:IssueDateTime/udt:DateTimeString[@format="102"] | 1..1 | Format as YYYYMMDD with @format="102" | BR-03 ↗ |
| line_items[].price & quantity Decimal String | BT-131 (Line Net Amount) | ram:SpecifiedTradeSettlementLineMonetarySummation/ram:LineTotalAmount | 1..n | Compute net line total rounded to 2 decimals before summing BT-106 | BR-CO-10 ↗ |
| line_items[].tax_lines[].rate Float (0.19) | BT-151 / BT-152 | ram:ApplicableTradeTax/ram:CategoryCode | 1..n | Map rate > 0 to CategoryCode "S" and multiply rate * 100 (19.00) | BR-S-08 ↗ |
Test Your Shopify ZUGFeRD 2.3 (EN 16931 / Extended) XML Export Live
Validate your generated CII-D16B payload against EN 16931 & ZUGFeRD 2.3 (EN 16931 / Extended) rules directly in your browser.
Missing <cbc:CustomizationID> or value does not declare EN 16931 CIUS compliance.
Remediation: Insert <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>.
Found invalid or lowercase currency code "eur". Expected uppercase ISO 4217 (e.g. "EUR").
Remediation: Replace <cbc:DocumentCurrencyCode>eur</cbc:DocumentCurrencyCode> with uppercase "EUR".
Peppol Schematron forbids empty elements such as <cbc:AdditionalStreetName></cbc:AdditionalStreetName> serialized from null ERP fields.
Remediation: Strip empty <cbc:AdditionalStreetName> nodes prior to XML serialization.
Missing <cbc:EndpointID schemeID="..."> inside <cac:AccountingSupplierParty>/<cac:Party>.
Remediation: Add <cbc:EndpointID schemeID="9930">DE123456789</cbc:EndpointID> as the first child of Seller <cac:Party>.
Buyer <cbc:EndpointID> is either missing or lacks the mandatory EAS @schemeID attribute.
Remediation: Add schemeID="9930" (or "0088" for GLN / "0204" for Leitweg-ID) to Buyer <cbc:EndpointID>.
No <cbc:BuyerReference> (BT-10) found. Mandatory in XRechnung 3.0 (BR-DE-15) and required in Peppol BIS 3.0 (PEPPOL-EN16931-R003) when OrderReference is absent.
Remediation: Insert <cbc:BuyerReference>991-12849-74</cbc:BuyerReference> in the document header.
Mathematical discrepancy of 0.05 EUR between InvoiceLine sum (199.95) and LegalMonetaryTotal/LineExtensionAmount (200.00).
Remediation: Set cbc:LineExtensionAmount and cbc:TaxExclusiveAmount to 199.95.
TaxSubtotal/TaxableAmount reports 200.00, but Standard rated ("S") lines total 199.95.
Remediation: Recalculate BT-116 = 199.95, VAT BT-117 = 37.99, and PayableAmount BT-115 = 237.94.
Other ERP to E-Invoicing Compliance Bridges
Unlock Pro Batch XML / PDF Converter ($29/mo) →4 mandatory EN 16931 Business Term mappings
4 mandatory EN 16931 Business Term mappings
4 mandatory EN 16931 Business Term mappings
4 mandatory EN 16931 Business Term mappings