Polish KSeF FA_VAT FA(3)

Key: pl-favat-v3 Module: github.com/invopop/gobl

Correction Definitions

Auto-generation of corrective invoices or credit and debit notes is supported.

Invoice Types

The types of invoices that can be created with a preceding definition:

credit-note

Stamp Keys

Stamp keys from the previous invoice that need to be referenced:

favat-ksef-number

Scenarios

bill/invoice

Regular Invoice

Filters:

Types: standard

Output:

Extensions: pl-favat-invoice-type:VAT

Prepayment Invoice

Filters:

Types: standard
Tags: partial

Output:

Extensions: pl-favat-invoice-type:ZAL

Settlement Invoice

Filters:

Types: standard
Tags: settlement

Output:

Extensions: pl-favat-invoice-type:ROZ

Simplified Invoice

Filters:

Types: standard
Tags: simplified

Output:

Extensions: pl-favat-invoice-type:UPR

Credit note

Filters:

Types: credit-note

Output:

Extensions: pl-favat-invoice-type:KOR

Prepayment credit note

Filters:

Types: credit-note
Tags: partial

Output:

Extensions: pl-favat-invoice-type:KOR_ZAL

Settlement credit note

Filters:

Types: credit-note
Tags: settlement

Output:

Extensions: pl-favat-invoice-type:KOR_ROZ

Extensions

Tax categories for KSeF

The pl-favat-tax-category extension specifies tax categories for Polish FA_VAT/KSeF invoices. Each category corresponds to a field in the FA_VAT XML schema (P_13_, P_14_, etc.). This extension is used at the line tax level (lines[].taxes[]) and is automatically normalized by GOBL based on the tax combo key, rate, and country fields. The extension is required for all line items. If the tax combo has a country set to a value other than PL, the category is automatically set to 8 (outside scope), regardless of the key and rate values. Automatic mapping from GOBL tax combos (when country is PL or empty):

GOBL Tax Key	GOBL Rate	FA_VAT Category	VAT %
`standard`	`general`	1	23%
`standard`	`reduced`	2	8%
`standard`	`super-reduced`	3	5%
`zero`	-	6.1	0%
`intra-community`	-	6.2	0%
`export`	-	6.3	0%
`exempt`	-	7	-
`outside-scope`	-	8	-
`reverse-charge`	-	9	-
(non-PL country)	(any)	8	-

Example:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	// ...
	"lines": [
		{
			// ...
			"taxes": [
				{
					"cat": "VAT",
					"key": "standard",
					"rate": "general",
					"percent": "23.0%",
					// Extension automatically set to "1"
					"ext": {
						"pl-favat-tax-category": "1"
					}
				}
			]
		}
	]
}

The ones that are not automatically mapped can be set manually.

pl-favat-tax-category

Code	Name
`1`	Base rate
`2`	First reduced rate
`3`	Second reduced rate
`4`	Taxi Rate
`5`	OSS (one stop shop)
`6.1`	0% VAT
`6.2`	0% VAT for intra-community supply of goods
`6.3`	0% VAT for export
`7`	Exempt
`8`	Foreign sales outside scope of Polish VAT
`9`	EU Reverse Charge
`10`	Domestic Reverse charge
`11`	Margin scheme

Invoice type code for KSeF

The pl-favat-invoice-type extension specifies the type of invoice for Polish FA_VAT/KSeF. This extension is used in the invoice tax section (tax.ext) and is automatically normalized by GOBL based on the invoice type and tags during the scenarios normalization step. Automatic mapping from GOBL invoice structure:

Tags	GOBL invoice type	Code	Description
-	`standard`	VAT	Regular invoice
`partial`	`standard`	ZAL	Advance invoice
`settlement`	`standard`	ROZ	Settlement invoice
`simplified`	`standard`	UPR	Simplified invoice
-	`credit-note`	KOR	Credit note
`partial`	`credit-note`	KOR_ZAL	Advance credit note
`settlement`	`credit-note`	KOR_ROZ	Settlement credit note

Example of an advance invoice:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$addons": ["pl-favat-v3"],
	"$tags": ["partial"],
	"type": "standard",
	// ...
	"tax": {
		// Extension automatically set to "ZAL"
		"ext": {
			"pl-favat-invoice-type": "ZAL"
		}
	}
}

pl-favat-invoice-type

Code	Name
`VAT`	Regular Invoice
`ZAL`	Advance Invoice
`ROZ`	Settlement Invoice
`UPR`	Simplified Invoice
`KOR`	Credit note
`KOR_ZAL`	advance credit note
`KOR_ROZ`	Settlement credit note

Cash accounting flag for KSeF

The pl-favat-cash-accounting extension indicates whether an invoice uses cash accounting for VAT purposes (kasowa metoda rozliczenia VAT). This extension is used in the invoice tax section (tax.ext). This extension is not normalized automatically and must be set manually by the user when the cash accounting method applies. According to Polish VAT law (Article 19a sec. 5 item 1 or Article 21 sec. 1), certain small businesses may account for VAT on a cash basis rather than accrual basis. Values:

“1”: Cash accounting applies
“2”: Normal accounting (accrual basis) - default

Example with cash accounting:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$addons": ["pl-favat-v3"],
	// ...
	"tax": {
		"ext": {
			"pl-favat-cash-accounting": "1"
		}
	}
}

pl-favat-cash-accounting

Code	Name
`1`	Cash accounting
`2`	No cash accounting

Self-invoicing flag for KSeF

The pl-favat-self-billing extension indicates whether an invoice is self-billed (samofakturowanie), where the buyer issues the invoice on behalf of the supplier. This extension is used in the invoice tax section (tax.ext). This extension is automatically normalized by GOBL:

When the invoice has the self-billed tag, the value is set to “1”
Otherwise, the value defaults to “2”

Self-billing is permitted under Article 106d sec. 1 of the Polish VAT Act when there is a prior agreement between the parties. Values:

“1”: Self-billed invoice
“2”: Regular invoice - default

Example of a self-billed invoice:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$addons": ["pl-favat-v3"],
	"$tags": ["self-billed"],
	// ...
	"tax": {
		// Extension automatically set to "1"
		"ext": {
			"pl-favat-self-billing": "1"
		}
	}
}

pl-favat-self-billing

Code	Name
`1`	Self-invoicing
`2`	Not self-invoicing

Reverse charge code for KSeF

The pl-favat-reverse-charge extension indicates whether the reverse charge mechanism applies to an invoice. This extension is used in the invoice tax section (tax.ext). This extension is automatically normalized by GOBL:

When the invoice has the reverse-charge tag, the value is set to “1”
Otherwise, the value defaults to “2”

Under the reverse charge mechanism (odwrotne obciążenie), the buyer rather than the seller is responsible for accounting for the VAT. This applies to:

EU intra-community services (B2B cross-border services)
Domestic reverse charge for specific goods and services listed in Polish VAT law
Imports of services from outside the EU

When using reverse charge, the line items should use the reverse-charge tax key, which automatically sets the tax category to “9” (EU Reverse Charge) or “10” (Domestic Reverse Charge) depending on the scenario. Values:

“1”: Reverse charge applies
“2”: Normal charge - default

Example of an EU reverse charge invoice:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$addons": ["pl-favat-v3"],
	"$tags": ["reverse-charge"],
	// ...
	"lines": [
		{
			// ...
			"taxes": [
				{
					"cat": "VAT",
					"key": "reverse-charge"
				}
			]
		}
	],
	"tax": {
		// Extension automatically set to "1"
		"ext": {
			"pl-favat-reverse-charge": "1"
		}
	}
}

pl-favat-reverse-charge

Code	Name
`1`	Reverse charge
`2`	No reverse charge

Split payment mechanism flag for KSeF

The pl-favat-split-payment-mechanism extension indicates whether the mandatory split payment mechanism (mechanizm podzielonej płatności, MPP) applies to an invoice. This extension is used in the invoice tax section (tax.ext). This extension is not normalized automatically and must be set manually when the split payment mechanism applies. According to Polish VAT law, split payment is mandatory when ALL of the following conditions are met:

The invoice amount exceeds PLN 15,000 (or equivalent in foreign currency)
The invoice covers goods or services listed in Annex 15 to the VAT Act
The transaction is B2B (business to business)
The invoice bears the note “split payment mechanism”

Under split payment, the buyer pays the VAT portion to a separate VAT account rather than to the seller directly. Values:

“1”: Split payment mechanism applies
“2”: Normal payment - default

Example:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$addons": ["pl-favat-v3"],
	// ...
	"tax": {
		"ext": {
			"pl-favat-split-payment-mechanism": "1"
		}
	},
	"notes": [
		{
			"key": "general",
			"text": "Mechanizm podzielonej płatności"
		}
	]
}

pl-favat-split-payment

Code	Name
`1`	Split payment mechanism
`2`	No split payment mechanism

Tax exemption code for KSeF

Extension used to indicate the type of reason for tax exemption code for KSeF. When the exempt tag is used in the invoice, having ext map’s pl-favat-exemption property is required. Also, it is required to add descriptive text for the legal basis for exemption. To do this in GOBL, add a note to the invoice with the exemption reason, in the following format:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	// ...

	"tax": {
		"ext": {
			"pl-favat-exemption": "A"
			// ...
		}
	},
	"notes": [
		{
			"key": "legal",
			"code": "A",
			"src": "pl-favat-exemption",
			"text": "Art. 25a ust. 1 pkt 9 ustawy o VAT"
		}
	]
}

In notes, code must match the code from the extension.

pl-favat-exemption

Code	Name
`A`	Law or act issued under the Polish law
`B`	Directive 2006/112/EC
`C`	Other legal basis

Margin scheme code for KSeF

The pl-favat-margin-scheme extension specifies the type of margin scheme (procedura marży) applied to an invoice. This extension is used in the invoice tax section (tax.ext). This extension is not normalized automatically and must be set manually when a margin scheme applies. Under margin schemes, VAT is calculated only on the seller’s margin (profit) rather than on the full sale price. This applies to specific business sectors in Poland:

Travel agencies (tour operators)
Sales of second-hand goods
Sales of works of art
Sales of collector’s items and antiques

When using a margin scheme, the tax category should typically be set to “11” (Margin scheme) in line items. Example for a travel agency:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$addons": ["pl-favat-v3"],
	// ...
	"tax": {
		"ext": {
			"pl-favat-margin-scheme": "2"
		}
	}
}

pl-favat-margin-scheme

Code	Name
`2`	Travel agency
`3.1`	Second-hand goods
`3.2`	Works of art
`3.3`	Antiques and collectibles

Payment method code for KSeF

The pl-favat-payment-means extension specifies the payment method used in an invoice. This extension is used in payment instructions (payment.instructions.ext) or payment advances (payment.advances[].ext). This extension is automatically normalized by GOBL based on the payment means key. The following table shows the mapping:

Code	FA_VAT Name	GOBL Payment Means Key
1	Cash	`cash`
2	Card	`card`
3	Voucher	`other+voucher`
4	Cheque	`cheque`
5	Credit/Loan	`other+credit`
6	Credit Transfer	`credit-transfer`
7	Mobile	`online`

Example with bank transfer payment:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$addons": ["pl-favat-v3"],
	// ...
	"payment": {
		"instructions": {
			"key": "credit-transfer",
			// Extension automatically set to "6"
			"ext": {
				"pl-favat-payment-means": "6"
			},
			"credit_transfer": [
				{
					"iban": "PL61109010140000071219812874",
					"name": "Company Name"
				}
			]
		}
	}
}

pl-favat-payment-means

Code	Name
`1`	Cash
`2`	Card
`3`	Coupon
`4`	Cheque
`5`	Loan
`6`	Wire Transfer
`7`	Mobile

Subordinate Local Government Unit flag

The pl-favat-jst extension indicates whether the customer is a Subordinate Local Government Unit (Jednostka Samorządu Terytorialnego - JST). This extension is used in the customer party section (customer.ext). This extension is not normalized automatically and must be set manually. When this extension is set to “1” (customer is JST), GOBL validates that the customer has an identity with role “8” (Local Government Unit - recipient) in the customer.identities array. This identity must include a code field with the JST identifier. Values:

“1”: Customer is a Subordinate Local Government Unit
“2”: Customer is not a JST - default

Example:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$addons": ["pl-favat-v3"],
	// ...
	"customer": {
		"name": "Gmina Warszawa",
		"tax_id": {
			"country": "PL",
			"code": "5252548806"
		},
		"ext": {
			"pl-favat-jst": "1"
		},
		"identities": [
			{
				"code": "146501",
				"ext": {
					"pl-favat-third-party-role": "8"
				}
			}
		]
	}
}

pl-favat-jst

Code	Name
`1`	Customer is a Subordinate Local Government Unit
`2`	Customer is not a Subordinate Local Government Unit

Group VAT member flag

The pl-favat-group-vat extension indicates whether the customer is a member of a VAT group (Grupa VAT - GV). This extension is used in the customer party section (customer.ext). This extension is not normalized automatically and must be set manually. VAT groups in Poland allow multiple legal entities to be treated as a single taxpayer for VAT purposes. When this extension is set to “1” (customer is a GV member), GOBL validates that the customer has an identity with role “10” (GV member - recipient) in the customer.identities array. This identity must include a code field with the VAT group member identifier. Values:

“1”: Customer is a VAT Group member
“2”: Customer is not a VAT Group member - default

Example:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$addons": ["pl-favat-v3"],
	// ...
	"customer": {
		"name": "Member Company Ltd.",
		"tax_id": {
			"country": "PL",
			"code": "1234567890"
		},
		"ext": {
			"pl-favat-group-vat": "1"
		},
		"identities": [
			{
				"code": "GV-12345",
				"ext": {
					"pl-favat-third-party-role": "10"
				}
			}
		]
	}
}

pl-favat-group-vat

Code	Name
`1`	Customer is a Group VAT member
`2`	Customer is not a Group VAT member

Third party role

The pl-favat-third-party-role extension specifies the role of a third party or additional entity in an invoice transaction. This extension is used in party identities (customer.identities[].ext, supplier.identities[].ext, or in additional parties). This extension is not normalized automatically and must be set manually based on the role of the entity in the transaction. Common use cases:

Role “8”: Required when customer has pl-favat-jst = “1” (Local Government Unit)
Role “10”: Required when customer has pl-favat-group-vat = “1” (VAT Group member)
Role “5”: When invoice is issued by an entity on behalf of the taxpayer
Other roles: For factoring, recipients, payers, etc.

Each identity with this extension should also include a code field with the identifier of the third party. Example with JST customer:

{
	"customer": {
		// ...
		"ext": {
			"pl-favat-jst": "1"
		},
		"identities": [
			{
				"code": "146501",
				"ext": {
					"pl-favat-third-party-role": "8"
				}
			}
		]
	}
}

pl-favat-third-party-role

Code	Name
`1`	Factor
`2`	Recipient
`3`	Original entity
`4`	Additional Purchaser
`5`	Invoice Issuer
`6`	Payer
`7`	Local Government Unit (LGU) - issuer
`8`	Local Government Unit (LGU) - recipient
`9`	GV member - issuer
`10`	GV member - recipient
`11`	Employee

Effective date code

The pl-favat-effective-date extension specifies when a correction invoice (credit note) becomes effective for VAT purposes. This extension is used in credit note tax section (tax.ext) when type is credit-note. This extension is not normalized automatically and it is not mandatory. It can be set manually for credit notes based on when the correction should take effect. According to Polish VAT regulations, a correction invoice can be effective:

On the date of the original invoice (code “1”)
On the date of the correction invoice itself (code “2”)
On another specific date, or different dates for different line items (code “3”)

Values:

“1”: Effective according to original invoice date
“2”: Effective according to correction date
“3”: Effective on another date (or multiple dates)

Example of a credit note effective on correction date:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$addons": ["pl-favat-v3"],
	"type": "credit-note",
	// ...
	"tax": {
		"ext": {
			"pl-favat-invoice-type": "KOR",
			"pl-favat-effective-date": "2"
		}
	},
	"preceding": [
		{
			"code": "INVOICE-001",
			"issue_date": "2025-01-15"
		}
	]
}

pl-favat-effective-date

Code	Name
`1`	Original
`2`	Correction
`3`	Other

Validation Rules

bill.Invoice

Field	Test	Validation Code / Message
Invoice	Can convert to [PLN]	`GOBL-PL-FAVAT-BILL-INVOICE-15` Invoice must be in PLN or provide exchange rate for conversion
Invoice	JST identity	`GOBL-PL-FAVAT-BILL-INVOICE-11` Customer requires identity with role ‘8’ and code for JST
Invoice	GroupVAT identity	`GOBL-PL-FAVAT-BILL-INVOICE-12` Customer requires identity with role ‘10’ and code for GroupVAT
Invoice	Exemption note present	`GOBL-PL-FAVAT-BILL-INVOICE-13` Missing exemption note
Invoice	Single exemption note	`GOBL-PL-FAVAT-BILL-INVOICE-14` Too many exemption notes
`type` Calculated	One of [standard, credit-note]	`GOBL-PL-FAVAT-BILL-INVOICE-01` Invoice type must be standard or credit-note
`preceding[*].issue_date`	Present	`GOBL-PL-FAVAT-BILL-INVOICE-02` Preceding issue date is required
`preceding[*].code`	Present	`GOBL-PL-FAVAT-BILL-INVOICE-03` Preceding code is required
`supplier`	Present	`GOBL-PL-FAVAT-BILL-INVOICE-04` Supplier is required
`supplier.tax_id`	Present	`GOBL-PL-FAVAT-BILL-INVOICE-16` Supplier tax ID is required
`supplier.tax_id.code`	Present	`GOBL-PL-FAVAT-BILL-INVOICE-17` Supplier tax ID code required
`supplier.name`	Present	`GOBL-PL-FAVAT-BILL-INVOICE-05` Supplier name is required
`supplier.addresses`	Present	`GOBL-PL-FAVAT-BILL-INVOICE-06` Supplier addresses are required
`supplier.addresses`	First address country	`GOBL-PL-FAVAT-BILL-INVOICE-07` Supplier first address must have a country
`supplier.addresses`	First address street	`GOBL-PL-FAVAT-BILL-INVOICE-08` Supplier first address must have a street
`customer`	Not simplified Present	`GOBL-PL-FAVAT-BILL-INVOICE-09` Customer is required
`customer.tax_id.code`	Code in [PL] Present	`GOBL-PL-FAVAT-BILL-INVOICE-10` Customer Polish tax ID code is required

tax.Combo

Field	Test	Validation Code / Message
`ext`	Ext require [pl-favat-tax-category]	`GOBL-PL-FAVAT-TAX-COMBO-01` Tax combo requires ‘pl-favat-tax-category’ extension

pay.Record

Field	Test	Validation Code / Message
`date`	Present	`GOBL-PL-FAVAT-PAY-RECORD-01` Advance payment date is required

Overview

Use Cases

Quick Start

Tax Regimes

Addons

Catalogues

Schemas (Draft 0)

Polish KSeF FA_VAT FA(3)

Correction Definitions

Invoice Types

Stamp Keys

Scenarios

bill/invoice

Extensions

Tax categories for KSeF

Invoice type code for KSeF

Cash accounting flag for KSeF

Self-invoicing flag for KSeF

Reverse charge code for KSeF

Split payment mechanism flag for KSeF

Tax exemption code for KSeF

Margin scheme code for KSeF

Payment method code for KSeF

Subordinate Local Government Unit flag

Group VAT member flag

Third party role

Effective date code

Validation Rules

​Correction Definitions

​Invoice Types

​Stamp Keys

​Scenarios

​bill/invoice

​Extensions

​Tax categories for KSeF

​Invoice type code for KSeF

​Cash accounting flag for KSeF

​Self-invoicing flag for KSeF

​Reverse charge code for KSeF

​Split payment mechanism flag for KSeF

​Tax exemption code for KSeF

​Margin scheme code for KSeF

​Payment method code for KSeF

​Subordinate Local Government Unit flag

​Group VAT member flag

​Third party role

​Effective date code

​Validation Rules

Correction Definitions

Invoice Types

Stamp Keys

Scenarios

bill/invoice

Extensions

Tax categories for KSeF

Invoice type code for KSeF

Cash accounting flag for KSeF

Self-invoicing flag for KSeF

Reverse charge code for KSeF

Split payment mechanism flag for KSeF

Tax exemption code for KSeF

Margin scheme code for KSeF

Payment method code for KSeF

Subordinate Local Government Unit flag

Group VAT member flag

Third party role

Effective date code

Validation Rules