> ## Documentation Index
> Fetch the complete documentation index at: https://gobl-cli-install-gobl-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Polish KSeF FA_VAT FA(3)
Key: `pl-favat-v3`
Module: [github.com/invopop/gobl](https://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
**Filters:**
* **Types:** `standard`
**Output:**
* **Extensions:** `pl-favat-invoice-type:VAT`
**Filters:**
* **Types:** `standard`
* **Tags:** `partial`
**Output:**
* **Extensions:** `pl-favat-invoice-type:ZAL`
**Filters:**
* **Types:** `standard`
* **Tags:** `settlement`
**Output:**
* **Extensions:** `pl-favat-invoice-type:ROZ`
**Filters:**
* **Types:** `standard`
* **Tags:** `simplified`
**Output:**
* **Extensions:** `pl-favat-invoice-type:UPR`
**Filters:**
* **Types:** `credit-note`
**Output:**
* **Extensions:** `pl-favat-invoice-type:KOR`
**Filters:**
* **Types:** `credit-note`
* **Tags:** `partial`
**Output:**
* **Extensions:** `pl-favat-invoice-type:KOR_ZAL`
**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:
```js theme={null}
{
"$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.
| 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:
```js theme={null}
{
"$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"
}
}
}
```
| 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:
```js theme={null}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$addons": ["pl-favat-v3"],
// ...
"tax": {
"ext": {
"pl-favat-cash-accounting": "1"
}
}
}
```
| 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:
```js theme={null}
{
"$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"
}
}
}
```
| 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:
```js theme={null}
{
"$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"
}
}
}
```
| 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:
```js theme={null}
{
"$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"
}
]
}
```
| 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:
```js theme={null}
{
"$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.
| 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:
```js theme={null}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$addons": ["pl-favat-v3"],
// ...
"tax": {
"ext": {
"pl-favat-margin-scheme": "2"
}
}
}
```
| 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:
```js theme={null}
{
"$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"
}
]
}
}
}
```
| 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:
```js theme={null}
{
"$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"
}
}
]
}
}
```
| 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:
```js theme={null}
{
"$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"
}
}
]
}
}
```
| 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:
```js theme={null}
{
"customer": {
// ...
"ext": {
"pl-favat-jst": "1"
},
"identities": [
{
"code": "146501",
"ext": {
"pl-favat-third-party-role": "8"
}
}
]
}
}
```
| 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:
```js theme={null}
{
"$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"
}
]
}
```
| Code | Name |
| - | - |
| `1` | Original |
| `2` | Correction |
| `3` | Other |
## Validation Rules
| Field | Test | Validation Code / Message |
| - | - | - |
| Invoice | | `GOBL-PL-FAVAT-BILL-INVOICE-15`
Invoice must be in PLN or provide exchange rate for conversion |
| Invoice | | `GOBL-PL-FAVAT-BILL-INVOICE-11`
Customer requires identity with role '8' and code for JST |
| Invoice | | `GOBL-PL-FAVAT-BILL-INVOICE-12`
Customer requires identity with role '10' and code for GroupVAT |
| Invoice | | `GOBL-PL-FAVAT-BILL-INVOICE-13`
Missing exemption note |
| Invoice | | `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` | | `GOBL-PL-FAVAT-BILL-INVOICE-02`
Preceding issue date is required |
| `preceding[*].code` | | `GOBL-PL-FAVAT-BILL-INVOICE-03`
Preceding code is required |
| `supplier` | | `GOBL-PL-FAVAT-BILL-INVOICE-04`
Supplier is required |
| `supplier.tax_id` | | `GOBL-PL-FAVAT-BILL-INVOICE-16`
Supplier tax ID is required |
| `supplier.tax_id.code` | | `GOBL-PL-FAVAT-BILL-INVOICE-17`
Supplier tax ID code required |
| `supplier.name` | | `GOBL-PL-FAVAT-BILL-INVOICE-05`
Supplier name is required |
| `supplier.addresses` | | `GOBL-PL-FAVAT-BILL-INVOICE-06`
Supplier addresses are required |
| `supplier.addresses` | | `GOBL-PL-FAVAT-BILL-INVOICE-07`
Supplier first address must have a country |
| `supplier.addresses` | | `GOBL-PL-FAVAT-BILL-INVOICE-08`
Supplier first address must have a street |
| `customer` | | `GOBL-PL-FAVAT-BILL-INVOICE-09`
Customer is required |
| `customer.tax_id.code` | | `GOBL-PL-FAVAT-BILL-INVOICE-10`
Customer Polish tax ID code is required |
| 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 |
| Field | Test | Validation Code / Message |
| - | - | - |
| `date` | | `GOBL-PL-FAVAT-PAY-RECORD-01`
Advance payment date is required |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.