JSON Invoice Fields to UBL XML (EN 16931 / Peppol BIS 3.0)

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.tax_currency_code	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 invoice.tax_currency_code is set; the buyer contact’s currency does not set it. Send it together with invoice.tax_amount_in_tax_currency (BT-111), which is rendered as a second cac:TaxTotal block in this currency. If you send only the code, the invoice is created but fails Peppol validation (BR-53, PEPPOL-EN16931-R054, PEPPOL-EN16931-R055). If you send only the amount, it is ignored.

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 as cac:AdditionalDocumentReference/cbc:ID instead of cac: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 an IssuedSelfInvoice, account data appears in AccountingCustomerParty (your company is the buyer) and invoice.contact data appears in AccountingSupplierParty (the contact is the supplier). The same applies symmetrically to ReceivedSelfInvoice.

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-46	Buyer Identifier	invoice.contact.party_identification	cac:AccountingCustomerParty/cac:Party/cac:PartyIdentification/cbc:ID @schemeID
BT-47	Buyer Legal Registration Identifier	invoice.contact.cin_value (cin_scheme)	cac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:CompanyID @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

Notes:

• BT-46: @schemeID is emitted, as 0009, only when the identifier equals the contact’s establishment SIRET; otherwise the element carries no @schemeID. In the French profiles (FRCIUS and FR extension) BT-46 does not come from party_identification: the contact’s SIRET is emitted with schemeID="0009" and, when the contact has one, the code service with schemeID="0224".
• BT-47: @schemeID is the ICD code of cin_scheme. When the contact has no cin_value, pin_value is emitted instead, and tin_value when there is no pin_value either. For a French contact the legal identifier is the SIREN: a suffix (8040) or a code routage (0224) stored as cin_value resolves to the SIREN under 0002; a SIRET (0009) resolves to the SIREN when the contact is an office and, in the French profiles, always.
• BT-31 and BT-48: cac:PartyTaxScheme/cac:TaxScheme/cbc:ID comes from the scheme of the identifier: VAT (or GST for the GST schemes) when the scheme is taxcode. When the party has no tin_value, the cin_value is written instead. If the scheme of that CIN is not taxcode (for example a GLN, 0088), the code is ZZZ and the document carries no VAT identifier. When the party has neither a TIN nor a CIN, the cac:PartyTaxScheme block is not written. It is not written either when the invoice carries a tax of category O. For the document to carry the VAT number of the buyer, store it in tin_value of the contact with a taxcode scheme (see Schemes). Only documents generated after the change carry it.

Import direction

When a UBL file is uploaded or received, the importer reads the buyer from cac:AccountingCustomerParty/cac:Party as follows:

• cbc:EndpointID and its @schemeID become pin_value and pin_scheme, as given. An endpoint with schemeID="EM" (email) is not read, and an endpoint equal to your own account’s Peppol address is discarded.
• cac:PartyLegalEntity/cbc:CompanyID and its @schemeID become cin_value and cin_scheme. A CompanyID that repeats the VAT number is discarded.
• When the file carries no CompanyID, the EndpointID fills the CIN only if its scheme is a company identifier scheme (for example 0002 or 0009), never a routing scheme (0224, 0225, 8040). From a 0225 endpoint the leading SIREN is derived and stored as cin_value under 0002.
• cac:PartyIdentification/cbc:ID becomes party_identification (BT-46); with several, the one under a company identifier scheme (a SIRET under 0009) wins, then the one without @schemeID. A SIRET under 0009 also fills the CIN when it is still empty.

The four French routing compositions (SIREN, SIREN_SIRET, SIREN_SIRET_CodeRoutage, SIREN_Suffix) travel as the value of cbc:EndpointID schemeID="0225" and are stored in pin_value unchanged: the importer neither composes nor splits the address. A CompanyID without @schemeID that equals the suffix of a SIREN_Suffix address is tagged with scheme 8040.

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-111	VAT Total in Tax Currency	invoice.tax_amount_in_tax_currency	cac:TaxTotal/cbc:TaxAmount (2nd block, currencyID = BT-6)
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
BT-120	VAT Exemption Reason Text	invoice_lines_attributes[].taxes_attributes[].comment	cac:TaxTotal/cac:TaxSubtotal/cac:TaxCategory/cbc:TaxExemptionReason
—	Withheld Amount	invoice.withheld_percent	cac:AllowanceCharge/cbc:Amount
—	Withheld Reason	invoice.amounts_withheld_reason	cac:AllowanceCharge/cbc:AllowanceChargeReason

VAT exemption reason (BT-120): the reason is entered on the tax of each line (taxes_attributes[].comment), but it is not written on the invoice line. B2Brouter groups the line taxes by category and rate into the VAT breakdown (cac:TaxTotal/cac:TaxSubtotal) and writes the reason there, once per group. If several lines of the same group carry different comments, only one of them is exported. It is exported for the exemption categories (E, AE, G, K, O) and omitted for S, Z, L and M, where EN 16931 does not allow it.

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