Paddle Billing to Peppol BIS Billing 3.0 Schema Crosswalk & XML Compiler
Why Native Paddle Billing Exports Fail Peppol BIS Billing 3.0 Validation
1. Paddle's `invoice_number` is a free-text string without a mandatory scheme identifier; Peppol requires BT-1 with a scheme (e.g., PEPPOL-EN16931-R008) and a separate BT-24 specification identifier, which Paddle does not provide.
2. Paddle's `details.totals.subtotal` is a float in minor units (e.g., 1000 for 10.00) and lacks tax-exclusive line extension amounts; Peppol BR-CO-10 and BR-CO-15 require exact decimal summation with 2-digit rounding, causing validation failures due to floating-point precision.
3. Paddle's `business.tax_identifier` is a single string without an EAS code or country prefix; Peppol mandates BT-31 (VAT identifier) and BT-48 (tax scheme) with ISO 6523 ICD, and for German receivers a Leitweg-ID (BT-10) or French SIREN (BT-30) must be present, which Paddle does not capture.
| Paddle Billing API Field | EN 16931 Business Term | Target UBL-2.1 XPath | Card. | Normalization Rule | Assertion |
|---|---|---|---|---|---|
| invoice_number string, e.g., 'INV-2024-001' | BT-1 | /Invoice/cbc:ID | 1..1 | Trim whitespace and replace any characters outside [A-Za-z0-9-] with '-'; if empty, generate a UUID v4 prefixed with 'PADDLE-'. Ensure uniqueness per invoice. | PEPPOL-EN16931-R008 β |
| currency_code string, ISO 4217 3-letter code, e.g., 'EUR' | BT-5 | /Invoice/cbc:DocumentCurrencyCode | 1..1 | Uppercase the value and validate against ISO 4217 list; if invalid, default to 'EUR' and log a warning. | BR-CL-01 β |
| business.tax_identifier string, e.g., 'DE123456789' | BT-31 | /Invoice/cac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID | 0..1 | Remove spaces and hyphens; if the string starts with a 2-letter country code, strip it and use the remainder as the VAT number; otherwise, prepend the supplier's country code from the seller address. Validate against the country's VAT regex. | BR-CO-15 β |
| details.totals.subtotal integer (minor units), e.g., 1000 for 10.00 | BT-106 | /Invoice/cac:LegalMonetaryTotal/cbc:LineExtensionAmount | 1..1 | Divide by 100 to convert to decimal, then round to 2 decimal places using half-up rounding. Ensure the sum of line extension amounts (BT-131) equals this value within 0.01 tolerance. | BR-CO-10 β |
Missing <cbc:CustomizationID> or value does not declare EN 16931 CIUS compliance.
fix: 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").
fix: 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.
fix: Strip empty <cbc:AdditionalStreetName> nodes prior to XML serialization.
Missing <cbc:EndpointID schemeID="..."> inside <cac:AccountingSupplierParty>/<cac:Party>.
fix: 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.
fix: 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.
fix: 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).
fix: Set cbc:LineExtensionAmount and cbc:TaxExclusiveAmount to 199.95.
TaxSubtotal/TaxableAmount reports 200.00, but Standard rated ("S") lines total 199.95.
fix: Recalculate BT-116 = 199.95, VAT BT-117 = 37.99, and PayableAmount BT-115 = 237.94.