> ## Documentation Index > Fetch the complete documentation index at: https://docs.invopop.com/llms.txt > Use this file to discover all available pages before exploring further. # Poland > Register suppliers and issue FA(3) invoices through Poland's KSeF 2.0 system.
View implementation guide ›
| | | | --------- | ------------------------------ | | Developer | [Invopop](https://invopop.com) | | Category | Government | | Scope | B2B | | Country | [Poland](/compliance/poland) | [KSeF](https://www.gov.pl/web/finanse) (Krajowy System e-Faktur) 2.0 is Poland's mandatory national e-invoicing system operated by the [Ministry of Finance](https://www.gov.pl/web/finanse). The system uses the FA(3) XML schema format for structured invoice data and provides real-time clearance for all B2B invoices. Electronic invoicing in Poland operates on a clearance model whereby every invoice must be validated against the FA(3) schema and business rules in real-time. Validated invoices receive a unique KSeF ID and official timestamp. The platform provides secure archiving for issued and received e-invoices. Invoices are encoded in FA(3), a strict XML format published and maintained by Polish tax authorities. The schema enforces standardized fields for both domestic and cross-border transactions, including buyer/seller data, VAT details, and item lines. **Key Features** * **Party Registration:** Register suppliers in the KSeF system with their Polish Tax ID (NIP). * **API Certificate Upload:** Upload KSeF certificates, private keys, and passwords programmatically via API for automated integration. * **Workflow Automation:** Automated workflows for registering parties, issuing invoices, and importing received invoices through the KSeF 2.0 system. * **Real-Time Validation:** Every invoice is validated in real-time against the FA(3) schema and business rules, ensuring compliance with Polish e-invoicing regulations. * **Invoice Import & Sync:** Automatically poll KSeF for received invoices and import them into Invopop in GOBL format. * **Legally Compliant PDF Invoices:** Invoices are generated with all mandatory fields and FA(3) QR codes linked to the KSeF portal. * **FA(3) XML Generation:** Compliant XML generation is supported for the KSeF FA(3) schema. * **QR Code:** Generates the FA(3) QR code according to KSeF specifications. * **KSeF 2.0 Integration:** Direct integration with KSeF 2.0, Poland's official national platform for electronic invoicing. **KSeF 2.0 Environment Support** Invopop supports KSeF 2.0 in sandbox (test and demo modes) and production environments. In sandbox, you can choose between test mode (with automatically generated certificates) or demo mode (simulating the real production flow). In production, all suppliers are registered directly with the KSeF production system. Make sure to check out our [Poland Guide](/guides/pl-ksef) for instructions on how to register suppliers, issue invoices, and set up your workflows. ## FAQ Invoicing questions International (cross-border) invoices are handled just like domestic invoices in KSeF: * The invoice is created in GOBL with the foreign recipient's details * It's converted to FA(3) XML format and submitted to KSeF * KSeF validates and clears the invoice, assigning a unique KSeF ID * The invoice is registered in the KSeF system However, since foreign recipients cannot access KSeF, you must deliver the invoice through other channels (email, EDI, etc.). Include the KSeF QR code in the delivery for verification purposes. **Test mode** (sandbox only): Uses self-signed certificates generated automatically by Invopop. Perfect for quick testing without accessing the KSeF portal. Invoices are not sent to real KSeF servers. **Demo mode** (sandbox only): Connects to the official [KSeF Demo Portal](https://ap-demo.ksef.mf.gov.pl/web/). Requires manual certificate generation, simulating the full production flow in a safe test environment. **Production mode** (live workspace): Connects to the live [KSeF Portal](https://ap.ksef.mf.gov.pl/). Requires valid company credentials and certificates. All invoices are submitted to the official KSeF system. Use test mode for initial integration testing, then switch to demo mode when you're ready to simulate the real certificate flow before going live. Official KSeF applications: * [KSeF Taxpayer Application](https://ksef.podatki.gov.pl/aplikacja-podatnika-ksef-i-inne-narzedzia/bezplatne-narzedzie-wersja-produkcyjna/) – the main portal with all functionalities * [KSeF Mobile Application](https://ksef.podatki.gov.pl/aplikacja-podatnika-ksef-i-inne-narzedzia/aplikacja-mobilna-ksef/) – a mobile app for on-the-go access * [e-mikrofirma](https://login.mf.gov.pl/Account/Select?ReturnUrl=%2Fconnect%2Fauthorize%2Fcallback%3Fclient_id%3D09e2877e-702a-4e27-8818-9472ca964c0a%26redirect_uri%3Dhttps%253A%252F%252Furzadskarbowy.gov.pl%26response_type%3Dcode%26scope%3Dprofile%2520openid%2520DataHub.UserAccess%2520eFormsClientApi.UserAccess%2520ChatApi.UserAccess%2520offline_access%26state%3D8f196c7682654d0da49b42bfc9045e51%26code_challenge%3DSIwxyxXJpAzUgzrMW96UIH9vNc6P0-dkdc7l482AWQA%26code_challenge_method%3DS256) – a simplified portal aimed at micro-entrepreneurs For testing: * [KSeF Demo Portal](https://ap-demo.ksef.mf.gov.pl/web/) – demo environment for testing Install the KSeF Poland app, register your supplier (Test, Demo, or Production environment), and run invoices through the Send Invoice workflow. Each environment requires its own NIP and certificate setup. This error means the uploaded KSeF certificate does not have the required permissions to issue invoices. This typically happens when the certificate was uploaded by someone who is not the company administrator and only has limited permissions granted by the main company account. The KSeF certificate uploaded to Invopop must belong to either: * The **company account** directly logged into KSeF, or * An entity that has both **InvoiceRead** and **InvoiceWrite** permissions (managed within KSeF) To resolve this, you have two options: 1. **Grant permissions in KSeF**: The company admin (or whoever has direct access to the KSeF company account) grants `InvoiceRead` and `InvoiceWrite` permissions to the user who uploaded the certificate to Invopop. This can be done from the [KSeF application portal](https://ap.ksef.mf.gov.pl/) and requires no further action in Invopop (no need to unregister/register). 2. **Re-register with a new certificate**: Unregister the supplier in Invopop and register it again using a certificate generated from the main KSeF company account (or another account with the required permissions). See the [Poland tax regime in GOBL](https://docs.gobl.org/regimes/pl) for tax categories and NIP rules. The [`pl-favat-v3`](https://docs.gobl.org/addons/pl-favat-v3) addon documents the FA(3) schema fields required for KSeF. Polish invoicing law requires a unit of measure for every line, and KSeF maps it to the `P_8A` field on each `FaWiersz`. Invopop supports two ways to populate it: 1. **Canonical unit code on `Item.Unit`** — preferred when the unit exists in the GOBL unit catalogue or as a UN/ECE Recommendation 20 code. For example, `Item.Unit: "H87"` (piece) or `Item.Unit: "KGM"` (kilogram). The gobl.ksef converter emits the UN/ECE code directly into `P_8A`. 2. **Free-form label on `Item.Meta["unit-label"]`** — use this for Polish abbreviations that do not match a canonical code, such as `"szt."` (sztuka — piece), `"usł."` (usługa — service), `"kpl."` (komplet — set) or `"opak."` (opakowanie — package). The value is passed through to `P_8A` unchanged, so the supplier's exact wording is preserved on the KSeF XML. Example line item using a free-form label: ```json theme={"system"} { "item": { "name": "Konsultacja prawna", "price": "200.00", "meta": { "unit-label": "usł." } }, "quantity": "1" } ``` When an inbound KSeF invoice contains a `P_8A` value that is not a recognised GOBL or UN/ECE code, gobl.ksef preserves the original string under `Item.Meta["unit-label"]` so round-trips do not lose the supplier's wording. `Item.Unit` is only populated when the value validates as a canonical code. Receiving questions Invopop automatically imports received invoices through a polling service: 1. **Configure polling interval** during party registration (hourly, daily, weekly, or monthly) 2. **Set up the sync workflow** to query KSeF for new invoices 3. **Configure the import workflow** to convert FA(3) XML to GOBL format 4. **Link the workflows** in the Poland app configuration The system automatically checks KSeF at your chosen interval and imports any new invoices to your configured folder. **For manual import**, use the API to trigger import jobs with specific KSeF numbers or date ranges. See the [Import Received Invoices](/guides/pl-ksef#import-received-invoices) section in the guide. Yes. You can manually trigger a sync workflow to import invoices from a specific date range using the [Create a Job endpoint](/api-ref/transform/jobs/create-a-job-post). Pass the `from` and `upto` date parameters to sync all invoices received within that period: ```json theme={"system"} { "workflow_id": "YOUR_SYNC_WORKFLOW_ID", "entry_id": "YOUR_PARTY_ENTRY_ID", "args": { "from": "2026-01-01T00:00:00Z", "upto": "2026-01-31T23:59:59Z" } } ``` This is useful for backfilling invoices after a polling outage or importing historical data before enabling automatic polling. Check these indicators: 1. **Polling configuration**: Verify the polling interval is set in your party registration workflow configuration 2. **App configuration**: Confirm the Poland app has your sync workflow configured 3. **Recent imports**: Check the "Invoices · Expenses" folder for newly imported invoices 4. **Job logs**: Review job logs in the Console for sync and import workflow executions 5. **Error notifications**: Set up email or Slack notifications in your workflow error handling to alert you of failures Test the import by manually triggering the sync workflow with a date range that includes known received invoices. FA(3) XML conforming to the Ministry of Finance schema. Each invoice carries a unique KSeF reference (numer KSeF) plus the issuer's signature and a QR code linking to the public verification page. Inbound FA(3) XMLs are parsed via [`gobl.favat`](https://github.com/invopop/gobl). Tax rates, line items, and parties map onto GOBL fields; the original signed XML is preserved as a silo entry attachment. Registering supplier questions Common reasons for registration failures: * **Certificate and private key mismatch**: Ensure you uploaded both files from the same certificate generation * **Incorrect password**: Verify the password matches what you set during certificate generation * **Future start date**: Certificate start date must be today or in the past * **Wrong portal environment**: Demo certificates won't work with production, and vice versa * **File encoding issues**: For API uploads, ensure files are properly base64-encoded * **Expired certificate**: Check that the certificate is still valid * **Invalid NIP**: Verify the Polish Tax ID is correct and has access to KSeF Check the workflow error logs in the Invopop Console for detailed error messages that can help diagnose the specific issue. **For sandbox testing**: * **Test mode**: Generate fake NIPs at [http://generatory.it/](http://generatory.it/). These work immediately with self-signed certificates. * **Demo mode**: You need a real NIP with access to the KSeF Demo Portal. Choose an environment (Test, Demo, or Production). Generate a KSeF certificate from the relevant portal (or use a self-signed cert in Test mode), upload it to Invopop with the matching password, and register the supplier through the KSeF Register Supplier workflow. A KSeF certificate exported as PKCS#12 (.p12) with password, generated through the KSeF Application Portal (or auto-generated by Invopop in Test mode). The certificate must have InvoiceRead + InvoiceWrite permissions. The KSeF certificate (PKCS#12 .p12 with password) is stored encrypted at rest. Invopop uses it to authenticate session creation with KSeF on the supplier's behalf; the password is never returned in API responses. More answers in our [Poland FAQ](/faq/poland) section The following workflow actions will be available once you install and enable this app:
1
Register a party (supplier) with the KSeF system using their Polish Tax ID (NIP).
1
Generate FA(3) XML from GOBL invoices for the KSeF system.
2
Submit FA(3) XML invoices to the KSeF clearance system and receive KSeF ID upon approval.
1
Import a received invoice from KSeF and convert it to GOBL format.
1
Query KSeF for received invoices in a time range and create import jobs for each invoice. The following workflows are available to make your integration easier. Use them as templates to build upon. This workflow registers a supplier in the KSeF system. ```json Example KSeF register supplier (send) workflow theme={"system"} { "name": "KSeF register supplier (send)", "description": "Register a supplier with KSeF for sending e-invoices", "schema": "org/party", "steps": [ { "id": "f6ca2240-fb6b-11f0-b2f4-37a8eb8f9eb9", "name": "Set state", "provider": "silo.state", "summary": "Set state to `processing`{.state .processing}", "config": { "state": "processing" } }, { "id": "f7315970-fb74-11f0-8137-27e02839a7ca", "name": "Register supplier with KSeF", "provider": "gov-pl.register" }, { "id": "3166cb10-fdba-11f0-a562-870ebfef62f3", "name": "Wait for KSeF certificate upload", "provider": "gov-pl.wait.upload" }, { "id": "f0b45d30-fb6b-11f0-b2f4-37a8eb8f9eb9", "name": "Set state", "provider": "silo.state", "summary": "Set state to `registered`{.state .registered}", "config": { "state": "registered" } } ], "rescue": [ { "id": "ebf99440-fb6b-11f0-b2f4-37a8eb8f9eb9", "name": "Set state", "provider": "silo.state", "summary": "Set state to `error`{.state .error}", "config": { "state": "error" } } ] } ``` [Add to my workspace →](https://console.invopop.com/redirect/workflows/new?template=pl-register) This workflow automates FA(3) Polish invoice processing and tax compliance. ```json Example KSeF issue invoice workflow theme={"system"} { "name": "KSeF issue invoice", "description": "Issue an invoice through KSeF", "schema": "bill/invoice", "steps": [ { "id": "20bbac70-fb6e-11f0-8a4e-79beeb9e3cf2", "name": "Set state", "provider": "silo.state", "summary": "Set state to `processing`{.state .processing}", "config": { "state": "processing" } }, { "id": "9b5f5330-fb70-11f0-bcdd-bdb71eaf1fb4", "name": "Add sequential code", "provider": "sequence.enumerate", "summary": "Dynamic · KSeF · 000001", "config": { "name": "KSeF", "padding": 6, "start": 1 } }, { "id": "2f41c860-fb6e-11f0-8a4e-79beeb9e3cf2", "name": "Sign envelope", "provider": "silo.close" }, { "id": "2b064190-fb6e-11f0-8a4e-79beeb9e3cf2", "name": "Generate FA_VAT v3 XML", "provider": "gov-pl.generate" }, { "id": "36ec8550-fb6e-11f0-8a4e-79beeb9e3cf2", "name": "Send invoice to KSeF", "provider": "gov-pl.send" }, { "id": "3a3e2150-fb6e-11f0-8a4e-79beeb9e3cf2", "name": "Set state", "provider": "silo.state", "summary": "Set state to `sent`{.state .sent}", "config": { "state": "sent" } } ], "rescue": [ { "id": "3eca1210-fb6e-11f0-8a4e-79beeb9e3cf2", "name": "Set state", "provider": "silo.state", "summary": "Set state to `error`{.state .error}", "config": { "state": "error" } } ] } ``` [Add to my workspace →](https://console.invopop.com/redirect/workflows/new?template=pl-send) This workflow imports a received invoice from KSeF and converts it to GOBL format. ```json Example KSeF import invoice workflow theme={"system"} { "name": "KSeF import invoice", "description": "Import an invoice received through KSeF", "schema": "bill/invoice", "steps": [ { "id": "ba8faad0-01d7-11f1-8b4e-fdb288ce1d84", "name": "Import invoice from KSeF", "provider": "gov-pl.import" }, { "id": "5efe18e0-01e7-11f1-8a2b-3f4babb9af4d", "name": "Set folder", "provider": "silo.folder", "summary": "Set folder to `Invoices · Expenses`{.font-medium}", "config": { "folder": "expenses" } }, { "id": "653ff700-01e7-11f1-8a2b-3f4babb9af4d", "name": "Set state", "provider": "silo.state", "summary": "Set state to `registered`{.state .registered}", "config": { "state": "registered" } } ], "rescue": [ { "id": "7d993da0-0275-11f1-94f6-05637523f70d", "name": "Set state", "provider": "silo.state", "summary": "Set state to `error`{.state .error}", "config": { "state": "error" } } ] } ``` [Add to my workspace →](https://console.invopop.com/redirect/workflows/new?template=pl-import) This workflow syncs all received invoices for a party within a specific time range and creates import jobs for each invoice found. ```json Example KSeF sync received invoices workflow theme={"system"} { "name": "KSeF sync received invoices", "description": "Sync received invoices from KSeF and dispatch import jobs", "schema": "org/party", "steps": [ { "id": "5bddfd40-0220-11f1-bd80-c7df39ccdf0b", "name": "Sync received invoices from KSeF", "provider": "gov-pl.sync" } ], "rescue": [] } ``` [Add to my workspace →](https://console.invopop.com/redirect/workflows/new?template=pl-sync) The following examples show partial [GOBL](https://docs.gobl.org) documents you can copy and paste directly into the [Invopop Console](https://console.invopop.com) or store via the API as silo entries. In this example, we're issuing a standard B2B invoice from a Polish supplier to another Polish business customer. Notice: * the minimal version (`ksef-b2b-standard.min.mdx`) contains only the essential fields required to create the invoice, * the [`pl-ksef-v1`](https://docs.gobl.org/addons/pl-ksef-v1) addon ensures the document will be validated using the KSeF rules built into the [GOBL](https://docs.gobl.org) library, * there are no totals or calculations in the minimal version; all these will be calculated automatically when running `gobl build`, * the built version (`ksef-b2b-standard.mdx`) shows the normalized document with calculated totals, line item sums, tax breakdowns, and automatically generated fields like `i` (line index), `sum`, and `total`, and, * make sure to process it with the "Issue KSeF invoice" workflow created during setup. ```json B2B Standard Invoice theme={"system"} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PL", "$addons": [ "pl-favat-v3" ], "series": "INVOICE", "code": "001", "issue_date": "2026-01-20", "supplier": { "name": "Testowa Firma Sp. z o.o.", "tax_id": { "country": "PL", "code": "9876543210" }, "addresses": [ { "street": "ul. Główna 1", "locality": "Warsaw", "code": "00-001", "country": "PL" } ], "emails": [ { "addr": "kontakt@testowa.pl" } ] }, "customer": { "name": "Klient Testowy Sp. z o.o.", "tax_id": { "country": "PL", "code": "1111111111" }, "addresses": [ { "street": "ul. Testowa 10", "locality": "Kraków", "code": "30-001", "country": "PL" } ] }, "lines": [ { "quantity": "10", "item": { "name": "Software Development Services", "price": "100.00", "unit": "h" }, "taxes": [ { "cat": "VAT", "rate": "general", "key": "standard" } ] }, { "quantity": "5", "item": { "name": "Consulting Services", "price": "150.00", "unit": "h" }, "taxes": [ { "cat": "VAT", "rate": "reduced", "key": "standard" } ] } ], "payment": { "instructions": { "key": "credit-transfer", "detail": "Transfer payment to our bank account", "credit_transfer": [ { "iban": "PL61109010140000071219812874", "name": "Testowa Firma Sp. z o.o." } ] } } } ``` ```json Built version theme={"system"} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PL", "$addons": [ "pl-favat-v3" ], "type": "standard", "series": "INVOICE", "code": "001", "issue_date": "2026-01-20", "currency": "PLN", "tax": { "ext": { "pl-favat-invoice-type": "VAT" } }, "supplier": { "name": "Testowa Firma Sp. z o.o.", "tax_id": { "country": "PL", "code": "9876543210" }, "addresses": [ { "street": "ul. Główna 1", "locality": "Warsaw", "code": "00-001", "country": "PL" } ], "emails": [ { "addr": "kontakt@testowa.pl" } ] }, "customer": { "name": "Klient Testowy Sp. z o.o.", "tax_id": { "country": "PL", "code": "1111111111" }, "addresses": [ { "street": "ul. Testowa 10", "locality": "Kraków", "code": "30-001", "country": "PL" } ] }, "lines": [ { "i": 1, "quantity": "10", "item": { "name": "Software Development Services", "price": "100.00", "unit": "h" }, "sum": "1000.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pl-favat-tax-category": "1" } } ], "total": "1000.00" }, { "i": 2, "quantity": "5", "item": { "name": "Consulting Services", "price": "150.00", "unit": "h" }, "sum": "750.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "reduced", "percent": "8.0%", "ext": { "pl-favat-tax-category": "2" } } ], "total": "750.00" } ], "payment": { "instructions": { "key": "credit-transfer", "detail": "Transfer payment to our bank account", "credit_transfer": [ { "iban": "PL61109010140000071219812874", "name": "Testowa Firma Sp. z o.o." } ], "ext": { "pl-favat-payment-means": "6" } } }, "totals": { "sum": "1750.00", "total": "1750.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pl-favat-tax-category": "1" }, "base": "1000.00", "percent": "23.0%", "amount": "230.00" }, { "key": "standard", "ext": { "pl-favat-tax-category": "2" }, "base": "750.00", "percent": "8.0%", "amount": "60.00" } ], "amount": "290.00" } ], "sum": "290.00" }, "tax": "290.00", "total_with_tax": "2040.00", "payable": "2040.00" } } ``` In this example, we're issuing a reverse charge invoice from a Polish supplier to a customer in another EU member state. Notice: * the customer has a valid EU VAT ID, indicating the transaction is subject to reverse charge mechanism, * the minimal version contains only essential fields; totals and tax calculations are omitted, * when running `gobl build`, the system automatically calculates totals, applies reverse charge rules, and normalizes the document, * the built version shows all calculated fields including the reverse charge indicator, tax breakdowns, and final totals, and, * the invoice is validated using the KSeF rules to ensure compliance with Polish e-invoicing requirements. ```json B2B Reverse Charge Invoice theme={"system"} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PL", "$addons": [ "pl-favat-v3" ], "$tags": [ "reverse-charge" ], "series": "RC", "code": "001", "issue_date": "2026-01-20", "supplier": { "name": "Testowa Firma Sp. z o.o.", "tax_id": { "country": "PL", "code": "9876543210" }, "addresses": [ { "street": "ul. Główna 1", "locality": "Warsaw", "code": "00-001", "country": "PL" } ] }, "customer": { "name": "EU Business GmbH", "tax_id": { "country": "DE", "code": "111111125" }, "addresses": [ { "street": "Hauptstraße 100", "locality": "Berlin", "code": "10115", "country": "DE" } ] }, "lines": [ { "quantity": "1", "item": { "name": "IT Services - EU Reverse Charge", "price": "5000.00" }, "taxes": [ { "cat": "VAT", "key": "reverse-charge" } ] } ], "notes": [ { "key": "legal", "text": "Reverse charge mechanism applies - VAT to be accounted for by the customer." } ] } ``` ```json Built version theme={"system"} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PL", "$addons": [ "pl-favat-v3" ], "$tags": [ "reverse-charge" ], "type": "standard", "series": "RC", "code": "001", "issue_date": "2026-01-20", "currency": "PLN", "tax": { "ext": { "pl-favat-invoice-type": "VAT", "pl-favat-reverse-charge": "1" } }, "supplier": { "name": "Testowa Firma Sp. z o.o.", "tax_id": { "country": "PL", "code": "9876543210" }, "addresses": [ { "street": "ul. Główna 1", "locality": "Warsaw", "code": "00-001", "country": "PL" } ] }, "customer": { "name": "EU Business GmbH", "tax_id": { "country": "DE", "code": "111111125" }, "addresses": [ { "street": "Hauptstraße 100", "locality": "Berlin", "code": "10115", "country": "DE" } ] }, "lines": [ { "i": 1, "quantity": "1", "item": { "name": "IT Services - EU Reverse Charge", "price": "5000.00" }, "sum": "5000.00", "taxes": [ { "cat": "VAT", "key": "reverse-charge", "ext": { "pl-favat-tax-category": "9" } } ], "total": "5000.00" } ], "totals": { "sum": "5000.00", "total": "5000.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "reverse-charge", "ext": { "pl-favat-tax-category": "9" }, "base": "5000.00", "amount": "0.00" } ], "amount": "0.00" } ], "sum": "0.00" }, "tax": "0.00", "total_with_tax": "5000.00", "payable": "5000.00" }, "notes": [ { "key": "legal", "text": "Reverse charge mechanism applies - VAT to be accounted for by the customer." } ] } ``` In this example, we're issuing a credit note to correct or refund a previous invoice. Notice: * the `type` field is set to `credit-note` to indicate this is a corrective document, * the `preceding` field references the original invoice being corrected, * the minimal version contains only the essential fields; calculations are handled by GOBL, * when running `gobl build`, the system automatically calculates negative totals, tax refunds, and validates the credit note structure, * the built version shows all calculated fields including negative amounts for the refund, and, * the document is validated using the KSeF rules to ensure compliance with Polish credit note requirements. ```json B2B Credit Note theme={"system"} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PL", "$addons": [ "pl-favat-v3" ], "type": "credit-note", "series": "KOR", "code": "001", "issue_date": "2026-01-20", "preceding": [ { "type": "standard", "issue_date": "2026-01-20", "series": "INVOICE", "code": "001", "reason": "Price correction", "stamps": [ { "prv": "favat-ksef-number", "val": "1234567890-20260120-ABCD1234-EF" } ], "ext": { "pl-favat-effective-date": "1" } } ], "supplier": { "name": "Testowa Firma Sp. z o.o.", "tax_id": { "country": "PL", "code": "9876543210" }, "addresses": [ { "street": "ul. Główna 1", "locality": "Warsaw", "code": "00-001", "country": "PL" } ] }, "customer": { "name": "Klient Testowy Sp. z o.o.", "tax_id": { "country": "PL", "code": "9876543210" }, "addresses": [ { "street": "ul. Testowa 10", "locality": "Kraków", "code": "30-001", "country": "PL" } ] }, "lines": [ { "quantity": "10", "item": { "name": "Software Development Services", "price": "10.00", "unit": "h" }, "taxes": [ { "cat": "VAT", "rate": "general", "ext": { "pl-favat-tax-category": "1" } } ] } ] } ``` ```json Built version theme={"system"} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PL", "$addons": [ "pl-favat-v3" ], "type": "credit-note", "series": "KOR", "code": "001", "issue_date": "2026-01-20", "currency": "PLN", "preceding": [ { "type": "standard", "issue_date": "2026-01-20", "series": "INVOICE", "code": "001", "reason": "Price correction", "stamps": [ { "prv": "favat-ksef-number", "val": "1234567890-20260120-ABCD1234-EF" } ], "ext": { "pl-favat-effective-date": "1" } } ], "tax": { "ext": { "pl-favat-invoice-type": "KOR" } }, "supplier": { "name": "Testowa Firma Sp. z o.o.", "tax_id": { "country": "PL", "code": "9876543210" }, "addresses": [ { "street": "ul. Główna 1", "locality": "Warsaw", "code": "00-001", "country": "PL" } ] }, "customer": { "name": "Klient Testowy Sp. z o.o.", "tax_id": { "country": "PL", "code": "9876543210" }, "addresses": [ { "street": "ul. Testowa 10", "locality": "Kraków", "code": "30-001", "country": "PL" } ] }, "lines": [ { "i": 1, "quantity": "10", "item": { "name": "Software Development Services", "price": "10.00", "unit": "h" }, "sum": "100.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pl-favat-tax-category": "1" } } ], "total": "100.00" } ], "totals": { "sum": "100.00", "total": "100.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pl-favat-tax-category": "1" }, "base": "100.00", "percent": "23.0%", "amount": "23.00" } ], "amount": "23.00" } ], "sum": "23.00" }, "tax": "23.00", "total_with_tax": "123.00", "payable": "123.00" } } ``` In this example, we're issuing a prepayment invoice to document an advance payment received before completing the delivery of goods or services. Notice: * the `$tags` field includes `partial`, which tells the FA\_VAT addon to classify this as a `ZAL` (Faktura Zaliczkowa) document type, * the `payment.advances` array records the advance payment details, including the mandatory `date` field and a `percent` of the total, * GOBL automatically calculates the advance amount from the percentage and deducts it from the payable total to produce the `due` amount, * the built version shows `"pl-favat-invoice-type": "ZAL"` automatically set in the tax extensions, and, * after sending this invoice through KSeF, reference the assigned KSeF number in the subsequent settlement invoice. ```json B2B Prepayment Invoice theme={"system"} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PL", "$addons": [ "pl-favat-v3" ], "$tags": ["partial"], "series": "ZAL", "code": "001", "issue_date": "2026-01-20", "supplier": { "name": "Testowa Firma Sp. z o.o.", "tax_id": { "country": "PL", "code": "9876543210" }, "addresses": [ { "street": "ul. Główna 1", "locality": "Warsaw", "code": "00-001", "country": "PL" } ] }, "customer": { "name": "Klient Testowy Sp. z o.o.", "tax_id": { "country": "PL", "code": "1111111111" }, "addresses": [ { "street": "ul. Testowa 10", "locality": "Kraków", "code": "30-001", "country": "PL" } ] }, "lines": [ { "quantity": "10", "item": { "name": "Software Development Services", "price": "100.00", "unit": "h" }, "taxes": [ { "cat": "VAT", "rate": "general", "key": "standard" } ] } ], "payment": { "advances": [ { "key": "credit-transfer", "description": "Advance payment for software development project", "date": "2026-01-20", "percent": "50%" } ], "instructions": { "key": "credit-transfer", "credit_transfer": [ { "iban": "PL61109010140000071219812874", "name": "Testowa Firma Sp. z o.o." } ] } } } ``` ```json Built version theme={"system"} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PL", "$addons": [ "pl-favat-v3" ], "$tags": [ "partial" ], "type": "standard", "series": "ZAL", "code": "001", "issue_date": "2026-01-20", "currency": "PLN", "tax": { "ext": { "pl-favat-invoice-type": "ZAL" } }, "supplier": { "name": "Testowa Firma Sp. z o.o.", "tax_id": { "country": "PL", "code": "9876543210" }, "addresses": [ { "street": "ul. Główna 1", "locality": "Warsaw", "code": "00-001", "country": "PL" } ] }, "customer": { "name": "Klient Testowy Sp. z o.o.", "tax_id": { "country": "PL", "code": "1111111111" }, "addresses": [ { "street": "ul. Testowa 10", "locality": "Kraków", "code": "30-001", "country": "PL" } ] }, "lines": [ { "i": 1, "quantity": "10", "item": { "name": "Software Development Services", "price": "100.00", "unit": "h" }, "sum": "1000.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pl-favat-tax-category": "1" } } ], "total": "1000.00" } ], "payment": { "advances": [ { "date": "2026-01-20", "key": "credit-transfer", "description": "Advance payment for software development project", "percent": "50%", "amount": "615.00", "ext": { "pl-favat-payment-means": "6" } } ], "instructions": { "key": "credit-transfer", "credit_transfer": [ { "iban": "PL61109010140000071219812874", "name": "Testowa Firma Sp. z o.o." } ], "ext": { "pl-favat-payment-means": "6" } } }, "totals": { "sum": "1000.00", "total": "1000.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pl-favat-tax-category": "1" }, "base": "1000.00", "percent": "23.0%", "amount": "230.00" } ], "amount": "230.00" } ], "sum": "230.00" }, "tax": "230.00", "total_with_tax": "1230.00", "payable": "1230.00", "advance": "615.00", "due": "615.00" } } ``` In this example, we're issuing a settlement invoice to finalize a transaction after one or more advance payments have been made. Notice: * the `$tags` field includes `settlement`, which tells the FA\_VAT addon to classify this as a `ROZ` (Faktura Rozliczeniowa) document type, * the `preceding` field references the original prepayment invoice, including its KSeF number stamp, * the `payment.advances` array records the previously paid advance amount, which GOBL deducts from the total to calculate the remaining `due`, * the line items represent the full value of the delivered goods or services, and, * the built version shows `"pl-favat-invoice-type": "ROZ"` automatically set in the tax extensions. ```json B2B Settlement Invoice theme={"system"} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PL", "$addons": [ "pl-favat-v3" ], "$tags": ["settlement"], "series": "ROZ", "code": "001", "issue_date": "2026-02-15", "preceding": [ { "type": "standard", "issue_date": "2026-01-20", "series": "ZAL", "code": "001", "stamps": [ { "prv": "favat-ksef-number", "val": "9876543210-20260120-ABCD1234-EF" } ] } ], "supplier": { "name": "Testowa Firma Sp. z o.o.", "tax_id": { "country": "PL", "code": "9876543210" }, "addresses": [ { "street": "ul. Główna 1", "locality": "Warsaw", "code": "00-001", "country": "PL" } ] }, "customer": { "name": "Klient Testowy Sp. z o.o.", "tax_id": { "country": "PL", "code": "1111111111" }, "addresses": [ { "street": "ul. Testowa 10", "locality": "Kraków", "code": "30-001", "country": "PL" } ] }, "lines": [ { "quantity": "10", "item": { "name": "Software Development Services", "price": "100.00", "unit": "h" }, "taxes": [ { "cat": "VAT", "rate": "general", "key": "standard" } ] } ], "payment": { "advances": [ { "description": "Advance payment per ZAL/001", "date": "2026-01-20", "amount": "615.00" } ], "instructions": { "key": "credit-transfer", "credit_transfer": [ { "iban": "PL61109010140000071219812874", "name": "Testowa Firma Sp. z o.o." } ] } } } ``` ```json Built version theme={"system"} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PL", "$addons": [ "pl-favat-v3" ], "$tags": [ "settlement" ], "type": "standard", "series": "ROZ", "code": "001", "issue_date": "2026-02-15", "currency": "PLN", "preceding": [ { "type": "standard", "issue_date": "2026-01-20", "series": "ZAL", "code": "001", "stamps": [ { "prv": "favat-ksef-number", "val": "9876543210-20260120-ABCD1234-EF" } ] } ], "tax": { "ext": { "pl-favat-invoice-type": "ROZ" } }, "supplier": { "name": "Testowa Firma Sp. z o.o.", "tax_id": { "country": "PL", "code": "9876543210" }, "addresses": [ { "street": "ul. Główna 1", "locality": "Warsaw", "code": "00-001", "country": "PL" } ] }, "customer": { "name": "Klient Testowy Sp. z o.o.", "tax_id": { "country": "PL", "code": "1111111111" }, "addresses": [ { "street": "ul. Testowa 10", "locality": "Kraków", "code": "30-001", "country": "PL" } ] }, "lines": [ { "i": 1, "quantity": "10", "item": { "name": "Software Development Services", "price": "100.00", "unit": "h" }, "sum": "1000.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pl-favat-tax-category": "1" } } ], "total": "1000.00" } ], "payment": { "advances": [ { "date": "2026-01-20", "description": "Advance payment per ZAL/001", "amount": "615.00" } ], "instructions": { "key": "credit-transfer", "credit_transfer": [ { "iban": "PL61109010140000071219812874", "name": "Testowa Firma Sp. z o.o." } ], "ext": { "pl-favat-payment-means": "6" } } }, "totals": { "sum": "1000.00", "total": "1000.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pl-favat-tax-category": "1" }, "base": "1000.00", "percent": "23.0%", "amount": "230.00" } ], "amount": "230.00" } ], "sum": "230.00" }, "tax": "230.00", "total_with_tax": "1230.00", "payable": "1230.00", "advance": "615.00", "due": "615.00" } } ``` B2C invoices are excluded from the mandatory e-invoicing requirement. The tax authority already receives B2C sales data through online fiscal cash registers that transmit receipts to the Central Repository of Cash Registers (CRK). However, businesses may voluntarily issue B2C invoices through KSeF. ```json KSeF B2C Invoice theme={"system"} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PL", "$addons": [ "pl-favat-v3" ], "$tags": [ "simplified" ], "uuid": "019c2849-dd61-7001-8c88-3c6d1aa83f8a", "type": "standard", "series": "SIMPLE", "code": "236", "issue_date": "2026-02-04", "currency": "PLN", "tax": { "ext": { "pl-favat-invoice-type": "UPR" } }, "supplier": { "name": "Testowa Firma Sp. z o.o.", "tax_id": { "country": "PL", "code": "9551893317" }, "addresses": [ { "street": "ul. Główna 1", "locality": "Warsaw", "code": "00-001", "country": "PL" } ], "emails": [ { "addr": "kontakt@testowa.pl" } ] }, "lines": [ { "i": 1, "quantity": "10", "item": { "name": "Software Development Services", "price": "100.00", "unit": "h" }, "sum": "1000.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pl-favat-tax-category": "1" } } ], "total": "1000.00" }, { "i": 2, "quantity": "5", "item": { "name": "Consulting Services", "price": "150.00", "unit": "h" }, "sum": "750.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "reduced", "percent": "8.0%", "ext": { "pl-favat-tax-category": "2" } } ], "total": "750.00" } ], "payment": { "instructions": { "key": "credit-transfer", "detail": "Transfer payment to our bank account", "credit_transfer": [ { "iban": "PL61109010140000071219812874", "name": "Testowa Firma Sp. z o.o." } ], "ext": { "pl-favat-payment-means": "6" } } }, "totals": { "sum": "1750.00", "total": "1750.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pl-favat-tax-category": "1" }, "base": "1000.00", "percent": "23.0%", "amount": "230.00" }, { "key": "standard", "ext": { "pl-favat-tax-category": "2" }, "base": "750.00", "percent": "8.0%", "amount": "60.00" } ], "amount": "290.00" } ], "sum": "290.00" }, "tax": "290.00", "total_with_tax": "2040.00", "payable": "2040.00" } } ``` ```json Built version theme={"system"} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PL", "$addons": [ "pl-favat-v3" ], "$tags": [ "simplified" ], "uuid": "019c2849-dd61-7001-8c88-3c6d1aa83f8a", "type": "standard", "series": "SIMPLE", "code": "236", "issue_date": "2026-02-04", "currency": "PLN", "tax": { "ext": { "pl-favat-invoice-type": "UPR" } }, "supplier": { "name": "Testowa Firma Sp. z o.o.", "tax_id": { "country": "PL", "code": "9551893317" }, "addresses": [ { "street": "ul. Główna 1", "locality": "Warsaw", "code": "00-001", "country": "PL" } ], "emails": [ { "addr": "kontakt@testowa.pl" } ] }, "lines": [ { "i": 1, "quantity": "10", "item": { "name": "Software Development Services", "price": "100.00", "unit": "h" }, "sum": "1000.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pl-favat-tax-category": "1" } } ], "total": "1000.00" }, { "i": 2, "quantity": "5", "item": { "name": "Consulting Services", "price": "150.00", "unit": "h" }, "sum": "750.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "reduced", "percent": "8.0%", "ext": { "pl-favat-tax-category": "2" } } ], "total": "750.00" } ], "payment": { "instructions": { "key": "credit-transfer", "detail": "Transfer payment to our bank account", "credit_transfer": [ { "iban": "PL61109010140000071219812874", "name": "Testowa Firma Sp. z o.o." } ], "ext": { "pl-favat-payment-means": "6" } } }, "totals": { "sum": "1750.00", "total": "1750.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pl-favat-tax-category": "1" }, "base": "1000.00", "percent": "23.0%", "amount": "230.00" }, { "key": "standard", "ext": { "pl-favat-tax-category": "2" }, "base": "750.00", "percent": "8.0%", "amount": "60.00" } ], "amount": "290.00" } ], "sum": "290.00" }, "tax": "290.00", "total_with_tax": "2040.00", "payable": "2040.00" } } ``` For more examples and detailed documentation, visit the [Poland Guide](/guides/pl-ksef). *** | | | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Compliance | [Invoicing compliance in Poland](/compliance/poland)
[Compliance timeline](/timelines/poland) | | Apps | [Poland](/apps/poland) | | Guides | [Poland Guide](/guides/pl-ksef) | | FAQ | [Poland FAQ](/faq/poland) | | GOBL | [Poland Tax Regime](https://docs.gobl.org/regimes/pl)
[Polish KSeF FA(3) Addon](https://docs.gobl.org/addons/pl-favat-v3) | Ask and answer questions about Poland App →