JSON Invoice Fields to KSeF FA(3) XML

Available from version 2025-10-13

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 KSeF FA(3) format (Polish National e-Invoice System).

Its purpose is to help understand how invoice data submitted in JSON format via the Invoice API corresponds to the KSeF FA(3) XML structure. Only fields that are actually mapped during tax report generation are included.

Note

KSeF uses a Poland-specific XML schema (FA variant 3, schema version 1-0E) which differs significantly from EN 16931 formats like UBL or CII. Not all EN 16931 Business Terms have a direct equivalent in KSeF, and KSeF introduces Poland-specific fields not present in the European standard.

Note

The seller/supplier information (Podmiot1) is automatically populated from your account settings. The buyer/customer information (Podmiot2) is populated from the invoice contact. If you need direct control over all fields, consider using the Tax Report API instead.

Header-Level Mapping

BT ID	Business Term	API Field (B2Brouter)	KSeF FA(3) XPath
BT-1	Invoice Number	invoice.number	Fa/P_2
BT-2	Invoice Issue Date	invoice.date	Fa/P_1
BT-3	Invoice Type Code	invoice.type_document Derived: defaults to VAT; KOR if amended invoice; ZAL if advance; UPR if simplified	Fa/RodzajFaktury
BT-5	Invoice Currency	invoice.currency	Fa/KodWaluty
BT-7	Tax Point Date	invoice.tax_point_date	Fa/P_6
BT-9	Payment Due Date	invoice.due_date	Fa/Platnosc/TerminPlatnosci/Termin
BT-25	Preceding Invoice Number	invoice.invoice_references[reference_type=amend].number (v2026-04-20+) or invoice.amended_number (older versions)	Fa/DaneFaKorygowanej/NrFaKorygowanej
BT-26	Preceding Invoice Issue Date	invoice.invoice_references[reference_type=amend].date (v2026-04-20+) or invoice.amended_date (older versions)	Fa/DaneFaKorygowanej/DataWystFaKorygowanej
—	Exchange Rate	invoice.exchange_rate	Fa/KursWalutyZ
BT-10	Buyer Reference	invoice.buyer_reference	Podmiot2/NrKlienta
BT-13	Purchase Order Reference	invoice.ponumber	Fa/WarunkiTransakcji/Zamowienia/NrZamowienia
BT-92	Purchase Order Date	invoice.order_date	Fa/WarunkiTransakcji/Zamowienia/DataZamowienia
BT-14	Sales Order Reference	invoice.sales_order_reference	Fa/DodatkowyOpis (key-value pair)
BT-16	Despatch Advice Reference	invoice.delivery_note_number	Fa/WZ
—	Correction Effect Code	invoice.amend_code_tax or tax_report_setting.credit_note_code	Fa/TypKorekty (only for KOR types)

Payment-Level Mapping

BT ID	Business Term	API Field (B2Brouter)	KSeF FA(3) XPath
BT-9	Payment Due Date	invoice.due_date	Fa/Platnosc/TerminPlatnosci/Termin
BT-81	Payment Means Code	invoice.payment_method (mapped to KSeF codes)	Fa/Platnosc/FormaPlatnosci
BT-84	Payee Financial Account IBAN	invoice.bank_account.iban	Fa/Platnosc/RachunekBankowy/NrRB
BT-84-0	Payee Financial Account Number	invoice.bank_account.number (fallback if no IBAN)	Fa/Platnosc/RachunekBankowy/NrRB
BT-85	Payee Financial Account Name	invoice.bank_account.name	Fa/Platnosc/RachunekBankowy/NazwaBanku
BT-86	Payee Financial Account BIC	invoice.bank_account.bic	Fa/Platnosc/RachunekBankowy/SWIFT
—	Paid Flag	Derived: 1 when payable_amount = 0 and total > 0	Fa/Platnosc/Zaplacono
—	Payment Date (when paid)	invoice.due_date (when Zaplacono=1)	Fa/Platnosc/DataZaplaty

Note: KSeF does not support card account details (BT-87, BT-88), direct debit mandates (BT-89), creditor references (BT-90), payment terms text (BT-20), or remittance information (BT-83).

Parties Mapping

This mapping is described for an issued invoice. If you want to map a received invoice, swap Podmiot1 and Podmiot2.

Podmiot1 (Seller/Supplier)

The Podmiot1 is automatically populated based on your account settings. This includes company name, NIP (Polish tax ID), and address.

BT ID	Business Term	API Field (B2Brouter)	KSeF FA(3) XPath
—	Seller Country Prefix	account.country (uppercased)	Podmiot1/PrefiksPodatnika
BT-31	Seller Tax Registration ID (NIP)	account.tin_value (without country prefix)	Podmiot1/DaneIdentyfikacyjne/NIP
BT-27	Seller Party Name	account.name	Podmiot1/DaneIdentyfikacyjne/Nazwa
BT-40	Seller Address Country	account.country (uppercased)	Podmiot1/Adres/KodKraju
BT-35	Seller Address Street	account.address	Podmiot1/Adres/AdresL1
BT-37,38	Seller Postal Code + City	account.postalcode + account.city	Podmiot1/Adres/AdresL2
BT-29-0	Seller GLN	account.cin_value (if cin_scheme = 88)	Podmiot1/Adres/GLN
BT-42	Seller Contact Telephone	account.phone	Podmiot1/DaneKontaktowe/Telefon
BT-43	Seller Contact Email	account.email	Podmiot1/DaneKontaktowe/Email
—	Seller REGON	account.routing_codes.cinX (scheme 8037)	Stopka/Rejestry/REGON
—	Seller KRS	account.routing_codes.cinX (scheme 8036)	Stopka/Rejestry/KRS
—	Seller BDO	account.routing_codes.cinX (scheme 8038)	Stopka/Rejestry/BDO

Podmiot2 (Buyer/Customer)

BT ID	Business Term	API Field (B2Brouter)	KSeF FA(3) XPath
BT-48	Buyer Tax Registration ID	invoice.contact.tin_value	PL: Podmiot2/DaneIdentyfikacyjne/NIP EU: Podmiot2/DaneIdentyfikacyjne/NrVatUE Non-EU: Podmiot2/DaneIdentyfikacyjne/NrID
—	Buyer Tax Country (EU)	invoice.contact.country (uppercased)	Podmiot2/DaneIdentyfikacyjne/KodUE (EU only)
—	Buyer Tax Country (Non-EU)	invoice.contact.country (uppercased)	Podmiot2/DaneIdentyfikacyjne/KodKraju (non-EU only)
—	No Tax ID Flag	Derived: 1 when contact.tin_value is blank	Podmiot2/DaneIdentyfikacyjne/BrakID
BT-44	Buyer Party Name	invoice.contact.name	Podmiot2/DaneIdentyfikacyjne/Nazwa
BT-55	Buyer Address Country	invoice.contact.country (uppercased)	Podmiot2/Adres/KodKraju
BT-50	Buyer Address Street	invoice.contact.address	Podmiot2/Adres/AdresL1
BT-52,53	Buyer Postal Code + City	invoice.contact.postalcode + invoice.contact.city	Podmiot2/Adres/AdresL2
BT-46-0	Buyer GLN	invoice.contact.cin_value (if cin_scheme = 88)	Podmiot2/Adres/GLN

Third Party Mapping (Podmiot3)

KSeF supports multiple third-party roles via the Podmiot3 element. A Podmiot3 is generated when delivery information is present or when the invoice has a third_party object (available from v2026-04-20).

Role Codes

Role Code	B2Brouter third_party.role	Description
2	delivery_recipient	Delivery recipient
3	original_supplier	Original entity (taken over/transformed)
4	additional_buyer	Additional purchaser
5	invoice_issuer	Invoice issuer on behalf of taxpayer
6	payer	Payer on behalf of purchaser
7	local_government_unit_issuer	Local government unit — issuer
8	local_government_unit_recipient	Local government unit — recipient (JST)
9	vat_group_member_issuer	VAT group member — issuer
10	vat_group_member_recipient	VAT group member — recipient (GV)
11	employee	Employee

Delivery (Role 2)

Delivery information is mapped to Podmiot3 with role code 2 when invoice.delivery_address is present. The delivery address is also duplicated under Fa/WarunkiTransakcji/Transport/WysylkaDo.

BT ID	Business Term	API Field (B2Brouter)	KSeF FA(3) XPath
BT-70	Delivery Party Name	invoice.delivery_party_name	Podmiot3/DaneIdentyfikacyjne/Nazwa
BT-71	Delivery Location ID (GLN)	invoice.delivery_location_id (if type is GLN/088)	Podmiot3/Adres/GLN
BT-75	Delivery Address Street	invoice.delivery_address	Podmiot3/Adres/AdresL1 and Fa/WarunkiTransakcji/Transport/WysylkaDo/AdresL1
BT-77,78	Delivery Postal Code + City	invoice.delivery_postalcode + invoice.delivery_city	Podmiot3/Adres/AdresL2 and Fa/WarunkiTransakcji/Transport/WysylkaDo/AdresL2
BT-80	Delivery Country	invoice.delivery_country	Podmiot3/Adres/KodKraju and Fa/WarunkiTransakcji/Transport/WysylkaDo/KodKraju
—	Third Party Role	Fixed: 2 (Recipient)	Podmiot3/Rola

Note: KSeF does not support delivery date (BT-72) or delivery period fields.

JST / GV / Other Roles (Roles 3–11) — v2026-04-20+

Changed in version 2026-04-20

Third-party support beyond delivery recipient.

Business Term	API Field (B2Brouter)	KSeF FA(3) XPath
Third Party Name	invoice.third_party.name	Podmiot3/DaneIdentyfikacyjne/Nazwa
Third Party Tax ID	invoice.third_party.tin_value	Podmiot3/DaneIdentyfikacyjne/NIP (PL), NrVatUE (EU), or NrID (non-EU)
Third Party Address	invoice.third_party.address	Podmiot3/Adres/AdresL1
Third Party Postal Code + City	invoice.third_party.postalcode + invoice.third_party.city	Podmiot3/Adres/AdresL2
Third Party Country	invoice.third_party.country	Podmiot3/Adres/KodKraju
Third Party Role	invoice.third_party.role → role code	Podmiot3/Rola
JST flag	invoice.apply_to_local_government_unit	Podmiot2/JST (1 when true, 2 when false)
GV flag	invoice.apply_to_vat_group_member	Podmiot2/GV (1 when true, 2 when false)

Invoice Line-Level Mapping (FaWiersz)

All attributes listed in the following table are properties of objects contained in the array: invoice.invoice_lines_attributes[]. The API Field column refers to keys within each invoice line object.

For regular invoices (VAT, KOR, UPR, ROZ), lines are rendered as FaWiersz elements. For advance payment invoices (ZAL, KOR_ZAL), lines are rendered as ZamowienieWiersz elements.

BT ID	Business Term	API Field (invoice line object)	KSeF FA(3) XPath
BT-126	Invoice Line ID	position	Fa/FaWiersz/NrWierszaFa
BT-153	Item Name	description	Fa/FaWiersz/P_7
BT-130	Billed Quantity (Unit Code)	unit (check API Reference for code list)	Fa/FaWiersz/P_8A
BT-129	Billed Quantity	quantity	Fa/FaWiersz/P_8B
BT-155	Item Seller Identifier	article_code	Fa/FaWiersz/Indeks
BT-157	Item Standard Identifier (GTIN)	article_code2	Fa/FaWiersz/GTIN
BT-146	Price Amount	price	Fa/FaWiersz/P_9A
-	Discount Unit Price	Derived from line allowance_charges_attributes[]{allowance_charge_indicator: "allowance"} amount / quantity	Fa/FaWiersz/P_10
BT-131	Line Net Amount	extension_amount (if not provided, it will be calculated)	Fa/FaWiersz/P_11
—	Line Tax Amount	Computed from taxes	Fa/FaWiersz/P_11Vat
—	Tax Code	Derived from tax characteristics	Fa/FaWiersz/P_12

Additional Item Properties Mapping (DodatkowyOpis per Line)

Each invoice line can carry additional key-value properties that map to line-level DodatkowyOpis elements in the KSeF XML.

All attributes listed in the following table are properties of objects contained in the array: invoice.invoice_lines_attributes[].additional_item_properties_attributes[].

BT ID	Business Term	API Field (additional item property object)	KSeF FA(3) XPath
—	Line Number Reference	Parent line’s position	Fa/DodatkowyOpis/NrWiersza
BT-160	Item Attribute Name	name (max 255 chars)	Fa/DodatkowyOpis/Klucz
BT-161	Item Attribute Value	value (max 255 chars)	Fa/DodatkowyOpis/Wartosc

Example JSON:

{
  "invoice": {
    "invoice_lines_attributes": [
      {
        "position": 1,
        "description": "Product A",
        "additional_item_properties_attributes": [
          { "name": "Color", "value": "Red" },
          { "name": "Size", "value": "XL" }
        ]
      }
    ]
  }
}

Resulting KSeF XML:

<tns:DodatkowyOpis>
  <tns:NrWiersza>1</tns:NrWiersza>
  <tns:Klucz>Color</tns:Klucz>
  <tns:Wartosc>Red</tns:Wartosc>
</tns:DodatkowyOpis>
<tns:DodatkowyOpis>
  <tns:NrWiersza>1</tns:NrWiersza>
  <tns:Klucz>Size</tns:Klucz>
  <tns:Wartosc>XL</tns:Wartosc>
</tns:DodatkowyOpis>

Special Property: unit_of_measure

Setting an additional item property with name unit_of_measure allows you to specify a free-text unit code for the line’s P_8A field in KSeF, overriding the standard unit codelist.

{
  "additional_item_properties_attributes": [
    { "name": "unit_of_measure", "value": "szt." }
  ]
}

This property is consumed directly as the line’s unit code (Fa/FaWiersz/P_8A) and is not emitted as a DodatkowyOpis element in the XML output.

Taxes Mapping

All attributes listed in the following table are properties of objects contained in the array: invoice.invoice_lines_attributes[].taxes_attributes[].

BT ID	Business Term	API Field (tax object)	KSeF FA(3) Mapping
BT-118	Tax Category Code	category (check our code list)	Used to derive P_12 tax code
BT-119	Tax Rate Applicable Percent	percent	Used to derive P_12 tax code and P_13_x/P_14_x aggregations
BT-120	Tax Exemption Reason	comment	Fa/Adnotacje/Zwolnienie/P_19A. Also accepts a KSeF P_12 code (zw, np I, np II, 0 KR, 0 WDT, 0 EX, oo) to override the derived value.

Tax Breakdown Aggregation (P_13_x / P_14_x)

KSeF requires tax amounts to be aggregated by rate at the header level. These fields are automatically computed from the invoice’s tax breakdowns:

KSeF Field	Description	Tax Rate / Category
P_13_1	Taxable base at basic rate	23% or 22%
P_14_1	Tax amount at basic rate	23% or 22%
P_14_1W	Tax amount at basic rate converted to PLN	23% or 22% (foreign currency invoices only)
P_13_2	Taxable base at first reduced rate	8% or 7%
P_14_2	Tax amount at first reduced rate	8% or 7%
P_14_2W	Tax amount at first reduced rate converted to PLN	8% or 7% (foreign currency invoices only)
P_13_3	Taxable base at second reduced rate	5%
P_14_3	Tax amount at second reduced rate	5%
P_14_3W	Tax amount at second reduced rate converted to PLN	5% (foreign currency invoices only)
P_13_6_1	Total value of domestic zero-rated sales	0% domestic (excluding intra-EU and export)
P_13_6_2	Total value of intra-Community supply of goods at 0%	0% intra-EU goods
P_13_6_3	Total value of exports at 0%	0% export
P_13_7	Total value of exempt sales	Exempt (category E, domestic scope)
P_13_8	Total value of cross-border reverse charge (np I)	Category AE, non-domestic scope
P_13_10	Total value of domestic reverse charge	Category AE, domestic scope
P_15	Total amount due (inclusive of all taxes)	Sum of all categories

Note

Fields P_14_xW (tax amounts converted to PLN) are only included for invoices in foreign currencies. The conversion uses the exchange_rate provided in the invoice.