Mapping JSON Invoice Fields to UBL XML (EN 16931 / Peppol BIS 3.0)
Invoice Field Mapping Guide (B2Brouter API ↔ Business Terms ↔ UBL XPath)
This guide details the mapping between the B2Brouter Invoice API fields, the corresponding Business Terms (BT) as defined by the European e-Invoicing standard (EN 16931), and the XML paths in the UBL 2.1 model (including Peppol BIS Billing 3.0).
Header-Level Mapping
| BT | Business Term | API Field (B2Brouter) | UBL XPath |
|---|---|---|---|
| BT-1 | Invoice number | invoice.number | cbc:ID |
| BT-2 | Invoice Issue Date | invoice.date | cbc:IssueDate |
| BT-3 | Invoice Type Code | invoice.type_code (api 2026-03-02) | cbc:InvoiceTypeCode (or cbc:CreditNoteTypeCode) |
| BT-5 | Document Currency | invoice.currency | cbc:DocumentCurrencyCode |
| BT-6 | Tax Currency Code | invoice.contact.currency | cbc:TaxCurrencyCode |
| BT-7 | Tax Point Date | invoice.tax_point_date | cbc:TaxPointDate |
| BT-9 | Payment Due Date | invoice.due_date | cbc:DueDate |
| BT-10 | Buyer Reference | invoice.buyer_reference | cbc:BuyerReference |
| BT-19 | Accounting Cost | invoice.buyer_accounting_reference | cbc:AccountingCost |
| BT-22 | Note (Header) | invoice.extra_info | cbc:Note |
| Notes: |
- BT-6: Emitted only when the buyer contact's currency differs from the invoice currency (BT-5) and tax amounts in that currency are present. When set, a second
cac:TaxTotalblock is rendered with amounts in this currency.
References & Periods
| BT | Business Term | API Field (B2Brouter) | UBL XPath |
|---|---|---|---|
| BT-13 | Purchase Order Reference | invoice.ponumber | cac:OrderReference/cbc:ID |
| BT-14 | Sales Order Reference | invoice.sales_order_reference | cac:OrderReference/cbc:SalesOrderID |
| BT-12 | Contract Reference | invoice.contract_number | cac:ContractDocumentReference/cbc:ID |
| BT-15 | Receiving Advice Reference | invoice.receiving_advice_reference | cac:ReceiptDocumentReference/cbc:ID |
| BT-16 | Despatch Advice Reference | invoice.delivery_note_number | cac:DespatchDocumentReference/cbc:ID |
| BT-25 | Preceding Invoice Ref | invoice.amended_number | cac:BillingReference/cac:InvoiceDocumentReference/cbc:ID |
| BT-26 | Preceding Invoice Date | invoice.amended_date | cac:BillingReference/cac:InvoiceDocumentReference/cbc:IssueDate |
| BT-73 | Invoicing Period Start | invoice.invoicing_period_start | cac:InvoicePeriod/cbc:StartDate |
| BT-74 | Invoicing Period End | invoice.invoicing_period_end | cac:InvoicePeriod/cbc:EndDate |
| BT-11 | Project Reference | invoice.file_reference | cac:ProjectReference/cbc:ID |
| — | Originator Document Ref | invoice.lot_reference | cac:OriginatorDocumentReference/cbc:ID |
| Notes: |
- For credit notes,
file_reference(BT-11) is emitted ascac:AdditionalDocumentReference/cbc:IDinstead ofcac:ProjectReference/cbc:ID.
Parties Mapping
This mapping is described for an issued invoice, if you want to map received invoice swap the AccountingSupplierParty and AccountingCustomerParty.
Seller Party
| BT | Business Term | API Field (B2Brouter) | UBL XPath |
|---|---|---|---|
| BT-34 | Seller Endpoint ID | account.pin_value | cac:AccountingSupplierParty/cac:Party/cbc:EndpointID @schemeID |
| BT-27 | Seller Legal Name | account.name | cac:AccountingSupplierParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName |
| BT-31 | Seller VAT Identifier | account.tin_value | cac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID |
| BT-35 | Seller Address Street | account.address | cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:StreetName |
| BT-36 | Seller Address Street 2 | account.address2 | cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:AdditionalStreetName |
| BT-37 | Seller Address City | account.city | cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:CityName |
| BT-38 | Seller Address Postal Code | account.postalcode | cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:PostalZone |
| BT-39 | Seller Province | account.province | cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:CountrySubentity |
| BT-40 | Seller Country | account.country | cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode |
| BT-41 | Seller Contact Name | account.contact_person | cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Name |
| BT-42 | Seller Contact Phone | account.phone | cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Telephone |
| BT-43 | Seller Contact Email | account.email | cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:ElectronicMail |
Buyer Party
| BT | Business Term | API Field (B2Brouter) | UBL XPath |
|---|---|---|---|
| BT-49 | Buyer Endpoint ID | invoice.contact.pin_value | cac:AccountingCustomerParty/cac:Party/cbc:EndpointID @schemeID |
| BT-44 | Buyer Legal Name | invoice.contact.name | cac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName |
| BT-45 | Buyer Trade Name | invoice.contact.name | cac:AccountingCustomerParty/cac:Party/cac:PartyName/cbc:Name |
| BT-48 | Buyer VAT Identifier | invoice.contact.tin_value | cac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID |
| BT-50 | Buyer Address Street | invoice.contact.address | cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:StreetName |
| BT-51 | Buyer Address Street 2 | invoice.contact.address2 | cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:AdditionalStreetName |
| BT-52 | Buyer Address City | invoice.contact.city | cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:CityName |
| BT-53 | Buyer Address Postal Code | invoice.contact.postalcode | cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:PostalZone |
| BT-54 | Buyer Province | invoice.contact.province | cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:CountrySubentity |
| BT-55 | Buyer Country | invoice.contact.country | cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode |
| BT-56 | Buyer Contact Name | invoice.contact.contact_person | cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Name |
| BT-57 | Buyer Contact Phone | invoice.contact.phone | cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Telephone |
| BT-58 | Buyer Contact Email | invoice.contact.email | cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:ElectronicMail |
Delivery
| BT | Business Term | API Field (B2Brouter) | UBL XPath |
|---|---|---|---|
| BT-72 | Delivery Date | invoice.delivery_date | cac:Delivery/cbc:ActualDeliveryDate |
| BT-71 | Delivery Location ID | invoice.delivery_location_id | cac:Delivery/cac:DeliveryLocation/cbc:ID |
| BT-75 | Delivery Address Street | invoice.delivery_address | cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:StreetName |
| BT-76 | Delivery Address Street 2 | invoice.delivery_address2 | cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:AdditionalStreetName |
| BT-77 | Delivery City | invoice.delivery_city | cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:CityName |
| BT-78 | Delivery Postal Code | invoice.delivery_postalcode | cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:PostalZone |
| BT-79 | Delivery Province | invoice.delivery_province | cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:CountrySubentity |
| BT-80 | Delivery Country | invoice.delivery_country | cac:Delivery/cac:DeliveryLocation/cac:Address/cac:Country/cbc:IdentificationCode |
| BT-70 | Delivery Party Name | invoice.delivery_party_name | cac:Delivery/cac:DeliveryParty/cac:PartyName/cbc:Name |
Payment
| BT | Business Term | API Field (B2Brouter) | UBL XPath |
|---|---|---|---|
| BT-81 | Payment Means Code | invoice.payment_method | cac:PaymentMeans/cbc:PaymentMeansCode @listID='UNCL4461' |
| BT-82 | Payment Means Text | invoice.payment_method_text | cac:PaymentMeans/cbc:PaymentMeansCode @name |
| BT-83 | Remittance Information | invoice.remittance_information | cac:PaymentMeans/cbc:PaymentID |
| BT-84 | Payee Bank Account IBAN | invoice.bank_account.iban | cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID |
| BT-84-0 | Payee Bank Account Number | invoice.bank_account.number | cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID (fallback when no IBAN) |
| BT-85 | Payee Bank Account Name | invoice.bank_account.name | cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:Name (currently not rendered) |
| BT-86 | Payee Bank Account BIC | invoice.bank_account.bic | cac:PaymentMeans/cac:PayeeFinancialAccount/cac:FinancialInstitutionBranch/cbc:ID |
| BT-87 | Card Account Number | invoice.card_account_attributes.account_number | cac:PaymentMeans/cac:CardAccount/cbc:PrimaryAccountNumberID |
| BT-87-0 | Card Account Holder Name | invoice.card_account_attributes.holder_name | cac:PaymentMeans/cac:CardAccount/cbc:HolderName |
| BT-88 | Card Account Network ID | invoice.card_account_attributes.network | cac:PaymentMeans/cac:CardAccount/cbc:NetworkID |
| BT-20 | Payment Terms | invoice.payment_terms | cac:PaymentTerms/cbc:Note |
| BT-89 | Mandate Reference (SEPA DD only) | invoice.mandate_reference_identifier | cac:PaymentMeans/cac:PaymentMandate/cbc:ID |
| BT-90 | Creditor Reference (SEPA DD) | invoice.bank_assigned_creditor_reference | cac:AccountingSupplierParty/cac:Party/cac:PartyIdentification/cbc:ID @schemeID='SEPA' |
| BT-91 | Debtor Account IBAN (SEPA DD) | invoice.contact_iban | cac:PaymentMeans/cac:PaymentMandate/cac:PayerFinancialAccount/cbc:ID |
Totals & Taxes
| BT | Business Term | API Field (B2Brouter) | UBL XPath |
|---|---|---|---|
| BT-106 | Line Net Amount Total | (calculated) | cac:LegalMonetaryTotal/cbc:LineExtensionAmount |
| BT-109 | Tax Exclusive Amount | (calculated) | cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount |
| BT-107 | Allowance Total Amount | (calculated) | cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount |
| BT-108 | Charge Total Amount | (calculated) | cac:LegalMonetaryTotal/cbc:ChargeTotalAmount |
| BT-112 | Tax Inclusive Amount | (calculated) | cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount |
| BT-113 | Total Prepaid Amount | invoice.payments_on_account | cac:LegalMonetaryTotal/cbc:PrepaidAmount |
| BT-114 | Rounding Amount | (from invoice adjustment) | cac:LegalMonetaryTotal/cbc:PayableRoundingAmount |
| BT-115 | Amount Due for Payment | invoice.payable_amount | cac:LegalMonetaryTotal/cbc:PayableAmount |
| BT-110 | Invoice Total VAT Amount | (calculated) | cac:TaxTotal/cbc:TaxAmount |
| BT-116 | VAT Category Taxable Amount | (calculated from lines) | cac:TaxTotal/cac:TaxSubtotal/cbc:TaxableAmount |
| BT-117 | VAT Category Tax Amount | (calculated from lines) | cac:TaxTotal/cac:TaxSubtotal/cbc:TaxAmount |
| — | Withheld Amount | invoice.withheld_percent | cac:AllowanceCharge/cbc:Amount |
| — | Withheld Reason | invoice.amounts_withheld_reason | cac:AllowanceCharge/cbc:AllowanceChargeReason |
Header Allowances & Charges
| BT | Business Term | API Field (B2Brouter) | UBL XPath |
|---|---|---|---|
| BT-92 | Allowance Amount | invoice.discount_amount | cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:Amount |
| BT-93 | Allowance Base Amount | (calculated when percent-based) | cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:BaseAmount |
| BT-94 | Allowance Percent | invoice.discount_percent | cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:MultiplierFactorNumeric |
| BT-97 | Allowance Reason | invoice.discount_text | cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:AllowanceChargeReason |
| BT-99 | Charge Amount | invoice.charge_amount | cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:Amount |
| BT-100 | Charge Base Amount | (calculated when percent-based) | cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:BaseAmount |
| BT-101 | Charge Percent | invoice.charge_percent | cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:MultiplierFactorNumeric |
| BT-104 | Charge Reason | invoice.charge_reason | cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:AllowanceChargeReason |
| BT-102 | Apply Tax To Allowance/Charge | invoice.apply_taxes_to_charge (default false) | cac:AllowanceCharge/cac:TaxCategory |
Invoice Line-Level Mapping
All attributes below are properties of objects in: invoice.invoice_lines_attributes[].
| BT | Business Term | API Field (invoice line) | UBL XPath |
|---|---|---|---|
| BT-126 | Invoice Line ID | position | cac:InvoiceLine/cbc:ID |
| BT-129 | Invoiced Quantity | quantity | cac:InvoiceLine/cbc:InvoicedQuantity |
| BT-130 | Invoiced Quantity (Unit) | unit | cac:InvoiceLine/cbc:InvoicedQuantity @unitCode |
| BT-131 | Line Extension Amount | extension_amount (or calculated) | cac:InvoiceLine/cbc:LineExtensionAmount |
| BT-146 | Price Amount | price | cac:InvoiceLine/cac:Price/cbc:PriceAmount |
| BT-153 | Item Name | description | cac:InvoiceLine/cac:Item/cbc:Name |
| BT-154 | Item Description | notes | cac:InvoiceLine/cac:Item/cbc:Description |
| BT-155 | Seller Item ID | article_code | cac:InvoiceLine/cac:Item/cac:SellersItemIdentification/cbc:ID |
| BT-156 | Buyer Item ID | article_code_buyer | cac:InvoiceLine/cac:Item/cac:BuyersItemIdentification/cbc:ID |
| BT-157 | Standard Item ID | article_code2 | cac:InvoiceLine/cac:Item/cac:StandardItemIdentification/cbc:ID @schemeID |
| BT-157-1 | Standard Item ID Scheme | article_code2_scheme | cac:InvoiceLine/cac:Item/cac:StandardItemIdentification/cbc:ID @schemeID (defaults to 0160) |
| BT-158 | Classification Code | classification_code | cac:InvoiceLine/cac:Item/cac:CommodityClassification/cbc:ItemClassificationCode @listID |
| BT-158-1 | Classification Code Scheme | classification_code_scheme | cac:InvoiceLine/cac:Item/cac:CommodityClassification/cbc:ItemClassificationCode @listID |
| BT-151 | VAT Category (per line) | taxes_attributes[].category | cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:ID |
| BT-152 | VAT Percent (per line) | taxes_attributes[].percent | cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:Percent |
| BT-120 | Tax Exemption Reason | taxes_attributes[].comment | cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:TaxExemptionReason |
| BT-160 | Additional Item Property Name | additional_item_properties_attributes[].name | cac:InvoiceLine/cac:Item/cac:AdditionalItemProperty/cbc:Name |
| BT-161 | Additional Item Property Value | additional_item_properties_attributes[].value | cac:InvoiceLine/cac:Item/cac:AdditionalItemProperty/cbc:Value |
| BT-133 | Buyer Accounting Reference | contact_reference | cac:InvoiceLine/cbc:AccountingCost |
| BT-134 | Invoicing Line Period Start | invoicing_period_start | cac:InvoiceLine/cac:InvoicePeriod/cbc:StartDate |
| BT-135 | Invoicing Line Period End | invoicing_period_end | cac:InvoiceLine/cac:InvoicePeriod/cbc:EndDate |
| BT-136 | Line Allowance Amount | discount_amount | cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:Amount |
| BT-138 | Line Allowance Percent | discount_percent | cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:MultiplierFactorNumeric |
| BT-139 | Line Allowance Reason | discount_text | cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:AllowanceChargeReason |
| BT-141 | Line Charge Amount | charge_amount | cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:Amount |
| BT-143 | Line Charge Percent | charge_percent | cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:MultiplierFactorNumeric |
| BT-144 | Line Charge Reason | charge_reason | cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:AllowanceChargeReason |
| BT-128 | Purchase Order Reference (line) | invoice_lines_attributes[].ponumber | cac:InvoiceLine/cac:DocumentReference/cbc:ID |
| BT-132 | PO Line Reference | invoice_lines_attributes[].sequence_number | cac:InvoiceLine/cac:OrderLineReference/cbc:LineID |
Updated about 18 hours ago