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.
Self-billing (
IssuedSelfInvoice/ReceivedSelfInvoice): in self-billing the buyer issues the invoice on behalf of the supplier, so the party roles in the XML are inverted relative to the API fields. For anIssuedSelfInvoice,accountdata appears inAccountingCustomerParty(your company is the buyer) andinvoice.contactdata appears inAccountingSupplierParty(the contact is the supplier). The same applies symmetrically toReceivedSelfInvoice. All XPaths in the tables below are filled from the appropriate party for the given role — the API field columns describe the normal issued mapping; for self-billing, swapaccount↔invoice.contact.
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 | allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X} | 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 | allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X} | cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:MultiplierFactorNumeric |
| BT-97 | Allowance Reason | allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."} | cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:AllowanceChargeReason |
| BT-99 | Charge Amount | allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X} | 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 | allowance_charges_attributes[]{allowance_charge_indicator: "charge", percentage: X} | cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:MultiplierFactorNumeric |
| BT-104 | Charge Reason | allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."} | cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:AllowanceChargeReason |
| BT-102 | Apply Tax To Allowance/Charge | allowance_charges_attributes[]{apply_taxes: true} | 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 | allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X} | cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:Amount |
| BT-138 | Line Allowance Percent | allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X} | cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:MultiplierFactorNumeric |
| BT-139 | Line Allowance Reason | allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."} | cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:AllowanceChargeReason |
| BT-141 | Line Charge Amount | allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X} | cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:Amount |
| BT-143 | Line Charge Percent | allowance_charges_attributes[]{allowance_charge_indicator: "charge", percentage: X} | cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:MultiplierFactorNumeric |
| BT-144 | Line Charge Reason | allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."} | 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 21 days ago