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

# KSeF issuing invoices guide

> Issue FA(3) invoices through Poland's KSeF 2.0 system.

export const WorkflowDiagram = ({workflow}) => {
  const stateColors = {
    processing: "yellow",
    sent: "blue",
    received: "blue",
    registered: "green",
    completed: "green",
    error: "red"
  };
  const StateChip = ({state, label}) => <Badge size="sm" color={stateColors[state] || "gray"} icon="square-small" iconType="solid">
      {label.charAt(0).toUpperCase() + label.slice(1)}
    </Badge>;
  const providerIcons = {
    "silo.state": "https://silo.invopop.com/images/status.svg",
    "silo.close": "https://silo.invopop.com/images/check-badge.svg",
    "silo.if": "https://assets.invopop.com/apps/silo/if.svg",
    "silo.folder": "https://silo.invopop.com/images/folder.svg",
    "silo.modify": "https://silo.invopop.com/images/modify.svg",
    "silo.correct": "https://silo.invopop.com/images/replace.svg",
    "silo.sleep": "https://assets.invopop.com/icons/sleep.svg",
    silo: "https://assets.invopop.com/apps/silo/icon.svg",
    "sequence.enumerate": "https://sequence.invopop.com/images/enumerate.svg",
    "transform.job.create": "https://transform.invopop.com/images/jobs.svg",
    webhook: "https://webhook.invopop.com/icon.svg",
    lookup: "https://lookup.invopop.com/icon.png",
    dropbox: "https://dropbox.invopop.com/icon.png",
    pdf: "https://pdf.invopop.com/file-pdf.svg",
    peppol: "https://assets.invopop.com/apps/peppol/icon.svg",
    ubl: "https://assets.invopop.com/apps/ubl/logo.svg",
    cii: "https://assets.invopop.com/apps/cii/logo.svg",
    "gov-dk": "https://assets.invopop.com/flags/dk.svg",
    "gov-fi": "https://assets.invopop.com/flags/fi.svg",
    "gov-fr": "https://assets.invopop.com/flags/fr.svg",
    "chorus-pro": "https://assets.invopop.com/apps/chroruspro/icon.svg",
    "gov-es": "https://assets.invopop.com/apps/gov-es/icon.svg",
    "gov-es.sii": "https://assets.invopop.com/apps/sii/icon.svg",
    "gov-es.ticketbai": "https://assets.invopop.com/apps/ticketbai/icon.svg",
    "gov-es.facturae": "https://assets.invopop.com/apps/facturae/icon.svg",
    verifactu: "https://assets.invopop.com/apps/verifactu/icon.svg",
    "gov-pl": "https://assets.invopop.com/apps/ksef/icon.svg",
    "gov-sa": "https://assets.invopop.com/apps/zatca/icon.svg",
    "gov-ar": "https://assets.invopop.com/apps/arca/icon.svg",
    "at-pt": "https://assets.invopop.com/apps/at-pt/icon.svg",
    "sat-mx": "https://assets.invopop.com/apps/sat-mexico/icon.svg",
    "sw-sapien": "https://assets.invopop.com/apps/sw-sapien/icon.svg",
    "sdi-it": "https://assets.invopop.com/apps/sdi-italy/icon.svg",
    "ticket-it": "https://assets.invopop.com/apps/agenzia-entrate/icon.svg",
    "nfe-br": "https://assets.invopop.com/apps/notas-fiscais-eletronicas-brazil/icon.svg",
    chargebee: "https://assets.invopop.com/apps/chargebee/icon.svg",
    stripe: "https://assets.invopop.com/apps/stripe/icon.svg",
    email: "https://assets.invopop.com/apps/email/icon.svg",
    cron: "https://assets.invopop.com/apps/cron/icon.svg",
    ilyda: "https://assets.invopop.com/apps/ilyda/icon.svg",
    invoicexpress: "https://assets.invopop.com/apps/invoicexpress/icon.svg",
    plemsi: "https://assets.invopop.com/flags/co.svg"
  };
  const iconFor = provider => {
    const parts = (provider || "").split(".");
    for (let i = parts.length; i > 0; i--) {
      const url = providerIcons[parts.slice(0, i).join(".")];
      if (url) return url;
    }
    return null;
  };
  const StepIcon = ({provider}) => {
    const url = iconFor(provider);
    return <span title={provider} className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md border border-gray-950/10 bg-white dark:border-white/10 dark:bg-white/5">
        {url ? <img src={url} alt="" className="h-4 w-4" /> : null}
      </span>;
  };
  const renderSummary = summary => {
    const nodes = [];
    const re = /`([^`]+)`(\{[^}]*\})?/g;
    let last = 0;
    let m;
    let k = 0;
    while ((m = re.exec(summary)) !== null) {
      if (m.index > last) nodes.push(summary.slice(last, m.index));
      const attrs = m[2] || "";
      if (attrs.indexOf(".state") >= 0) {
        const state = (attrs.match(/\.state\s+\.([\w-]+)/) || [])[1] || m[1];
        nodes.push(<StateChip key={k++} state={state} label={m[1]} />);
      } else if (attrs) {
        nodes.push(<span key={k++} className="text-sm font-medium text-gray-700 dark:text-gray-300">
            {m[1]}
          </span>);
      } else {
        nodes.push(<code key={k++} className="text-sm rounded bg-gray-100 px-1 font-mono text-sm dark:bg-white/10">
            {m[1]}
          </code>);
      }
      last = m.index + m[0].length;
    }
    if (last < summary.length) nodes.push(summary.slice(last));
    return nodes;
  };
  const NoteRow = ({text}) => <div className="mt-4 mb-1 font-mono text-sm leading-5 text-gray-400 dark:text-gray-500">{"// " + text}</div>;
  const renderSteps = (steps, counter) => (steps || []).map(step => {
    counter.n += 1;
    const n = counter.n;
    const branches = (step.next || []).filter(b => b.steps && b.steps.length > 0);
    return <div key={step.id || "step-" + n}>
          {step.notes ? <NoteRow text={step.notes} /> : null}
          <div className="mt-2.5 flex items-center">
            <span className="absolute left-0 w-10 text-center font-mono text-sm text-gray-400 select-none dark:text-gray-500">
              {n}
            </span>
            <div className="flex min-w-0 flex-1 items-center gap-2 rounded-xl border border-gray-950/5 bg-white px-2 py-2 dark:border-white/10 dark:bg-gray-900">
              <StepIcon provider={step.provider} />
              <span className="text-sm shrink-0 font-medium text-gray-900 dark:text-gray-100">{step.name}</span>
              {step.summary ? <span className="text-sm min-w-0 truncate text-gray-500 dark:text-gray-400">{renderSummary(step.summary)}</span> : null}
            </div>
          </div>
          {branches.length > 0 ? <div className="ml-5 border-l border-gray-200 -my-1 py-1 pl-6 dark:border-white/10">
              {branches.map((branch, bi) => <div key={branch.code || branch.status || bi}>
                  <div className="mt-4">
                    <span className="rounded-md bg-gray-200/70 px-2 py-1 font-mono text-sm text-gray-600 dark:bg-white/10 dark:text-gray-300">
                      {branch.code || branch.status}
                    </span>
                  </div>
                  {renderSteps(branch.steps, counter)}
                </div>)}
            </div> : null}
        </div>;
  });
  const counter = {
    n: 0
  };
  const wf = workflow || ({});
  return <div className="not-prose relative my-5 rounded-2xl border border-gray-950/5 bg-gray-50 py-3 pr-4 pb-5 pl-12 dark:border-white/10 dark:bg-white/[0.03]">
      {renderSteps(wf.steps, counter)}
      {wf.rescue && wf.rescue.length > 0 ? <div className="mt-6 border-t border-dashed border-gray-300 dark:border-white/10">
          <NoteRow text="If any step fails" />
          {renderSteps(wf.rescue, counter)}
        </div> : null}
    </div>;
};

export const plSendWorkflow = {
  "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"
    }
  }]
};

## Introduction

KSeF (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.

Invoices are encoded in FA(3), a strict XML format that enforces standardized fields for domestic and cross-border transactions. The KSeF system validates all submitted invoices in real-time and assigns a unique KSeF ID upon successful clearance.

This guide covers creating and sending FA(3) invoices through KSeF. Two companion guides cover the rest of the family:

* [Poland: Supplier registration](/guides/pl-ksef-supplier) — registering parties (suppliers) in the KSeF system.
* [Poland: Receiving invoices](/guides/pl-ksef-receiving) — automatically importing invoices received by your suppliers from KSeF.

## Prerequisites

To issue invoices through KSeF, you will need:

* **A registered party (supplier)**: follow the [KSeF supplier registration guide](/guides/pl-ksef-supplier) to connect the Poland app and register the party with KSeF before issuing.
* **Customer details**, including their Polish Tax ID (NIP) for domestic B2B invoices.
* **Line items** with quantities, prices, and applicable VAT rates.

## Setup

All of the following steps must be carried out from the [Invopop Console](https://console.invopop.com).

<Info>
  The Poland app must already be connected and the party registered with KSeF — both are covered in the [supplier registration guide](/guides/pl-ksef-supplier).
</Info>

<Steps>
  <Step title="Configure the invoice sending workflow">
    This workflow signs the GOBL document, converts it to FA(3) XML, and submits it to KSeF.

    <Card iconType="duotone" title="KSeF send invoice workflow" icon="code-branch" href="https://console.invopop.com/redirect/workflows/new?template=pl-send" horizontal>
      Add to my workspace →
    </Card>

    <Tabs>
      <Tab title="Workflow">
        <WorkflowDiagram workflow={plSendWorkflow} />
      </Tab>

      <Tab title="Code">
        Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view.

        ```json 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"
                    }
                }
            ]
        }
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Running

In this section, we'll provide details on how to issue invoices on behalf of a registered party.

### Send an invoice

Once a party is registered, you can issue invoices on their behalf. 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.

<Tip>
  GOBL Invoices sent to KSeF require the regime set to PL and addons must include pl-favat-v3 for FA(3) schema compliance.
</Tip>

<AccordionGroup>
  <Accordion title="B2B Standard Invoice">
    In this example, we're issuing a standard B2B invoice from a Polish supplier to another Polish business customer.

    Notice:

    * the minimal version in the first tab 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 in the second tab 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 "KSeF issue invoice" workflow created during setup.

    <CodeGroup>
      ```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": "Warszawa",
              "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": "Warszawa",
      				"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"
      	}
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="B2B Reverse Charge Invoice">
    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.

    <CodeGroup>
      ```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": "Warszawa",
              "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": "Warszawa",
      				"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."
      		}
      	]
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="B2B Credit Note">
    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.

    <CodeGroup>
      ```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": "Warszawa",
              "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": "Warszawa",
      				"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"
      	}
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="B2B Prepayment Invoice (Faktura Zaliczkowa)">
    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.

    <CodeGroup>
      ```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": "Warszawa",
              "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": "Warszawa",
      				"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"
      	}
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="B2B Settlement Invoice (Faktura Rozliczeniowa)">
    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.

    <CodeGroup>
      ```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": "Warszawa",
              "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": "Warszawa",
      				"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"
      	}
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="B2C Invoice (voluntary)">
    <Note>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.</Note>

    <CodeGroup>
      ```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": "Warszawa",
                      "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": "Warszawa",
      				"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"
      	}
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Self-billed Invoice">
    A self-billed invoice (samofakturowanie) is issued by the customer on behalf of the supplier, under a prior agreement between the two parties.

    <CodeGroup>
      ```json KSeF self-billed invoice theme={"system"}
      {
          "$schema": "https://gobl.org/draft-0/bill/invoice",
          "$regime": "PL",
          "$tags": [
              "self-billed"
          ],
          "code": "SAMPLE-001",
          "issue_date": "2025-08-01",
          "supplier": {
              "name": "Provide One S.L.",
              "tax_id": {
                  "country": "PL",
                  "code": "9876543210"
              },
              "addresses": [
                  {
                      "num": "42",
                      "street": "ul. Przykładowa",
                      "locality": "Warszawa",
                      "region": "mazowieckie",
                      "code": "00-015",
                      "country": "PL"
                  }
              ],
              "emails": [
                  {
                      "addr": "billing@example.com"
                  }
              ]
          },
          "customer": {
              "name": "Your Company S.A.",
              "tax_id": {
                  "country": "PL",
                  "code": "1234567788"
              },
              "addresses": [
                  {
                      "num": "43",
                      "street": "ul. Przykładowa",
                      "locality": "Warszawa",
                      "region": "mazowieckie",
                      "code": "00-015",
                      "country": "PL"
                  }
              ]
          },
          "lines": [
              {
                  "quantity": "20",
                  "item": {
                      "name": "Development services",
                      "price": "90.00",
                      "unit": "h"
                  },
                  "taxes": [
                      {
                          "cat": "VAT",
                          "rate": "general"
                      }
                  ]
              },
              {
                  "quantity": "1",
                  "item": {
                      "name": "Financial service",
                      "price": "10.00",
                      "unit": "service"
                  },
                  "taxes": [
                      {
                          "cat": "VAT",
                          "rate": "reduced"
                      }
                  ]
              }
          ]
      }
      ```

      ```json Built version theme={"system"}
      {
      	"$schema": "https://gobl.org/draft-0/bill/invoice",
      	"$regime": "PL",
      	"$tags": [
      		"self-billed"
      	],
      	"type": "standard",
      	"code": "SAMPLE-001",
      	"issue_date": "2025-08-01",
      	"currency": "PLN",
      	"supplier": {
      		"name": "Provide One S.L.",
      		"tax_id": {
      			"country": "PL",
      			"code": "9876543210"
      		},
      		"addresses": [
      			{
      				"num": "42",
      				"street": "ul. Przykładowa",
      				"locality": "Warszawa",
      				"region": "mazowieckie",
      				"code": "00-015",
      				"country": "PL"
      			}
      		],
      		"emails": [
      			{
      				"addr": "billing@example.com"
      			}
      		]
      	},
      	"customer": {
      		"name": "Your Company S.A.",
      		"tax_id": {
      			"country": "PL",
      			"code": "1234567788"
      		},
      		"addresses": [
      			{
      				"num": "43",
      				"street": "ul. Przykładowa",
      				"locality": "Warszawa",
      				"region": "mazowieckie",
      				"code": "00-015",
      				"country": "PL"
      			}
      		]
      	},
      	"lines": [
      		{
      			"i": 1,
      			"quantity": "20",
      			"item": {
      				"name": "Development services",
      				"price": "90.00",
      				"unit": "h"
      			},
      			"sum": "1800.00",
      			"taxes": [
      				{
      					"cat": "VAT",
      					"key": "standard",
      					"rate": "general",
      					"percent": "23.0%"
      				}
      			],
      			"total": "1800.00"
      		},
      		{
      			"i": 2,
      			"quantity": "1",
      			"item": {
      				"name": "Financial service",
      				"price": "10.00",
      				"unit": "service"
      			},
      			"sum": "10.00",
      			"taxes": [
      				{
      					"cat": "VAT",
      					"key": "standard",
      					"rate": "reduced",
      					"percent": "8.0%"
      				}
      			],
      			"total": "10.00"
      		}
      	],
      	"totals": {
      		"sum": "1810.00",
      		"total": "1810.00",
      		"taxes": {
      			"categories": [
      				{
      					"code": "VAT",
      					"rates": [
      						{
      							"key": "standard",
      							"base": "1800.00",
      							"percent": "23.0%",
      							"amount": "414.00"
      						},
      						{
      							"key": "standard",
      							"base": "10.00",
      							"percent": "8.0%",
      							"amount": "0.80"
      						}
      					],
      					"amount": "414.80"
      				}
      			],
      			"sum": "414.80"
      		},
      		"tax": "414.80",
      		"total_with_tax": "2224.80",
      		"payable": "2224.80"
      	}
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

After creating the invoice in the Console:

1. Click **Build** to validate
2. Click **Save** to store in the silo
3. Click **Select workflow** and choose the **KSeF Send Invoice** workflow
4. Click **Run workflow**

The invoice will be validated, converted to FA(3) XML format, and sent to KSeF. Upon successful clearance, it will receive a unique KSeF ID.

<Note>
  For international transactions, the invoice is created and cleared in KSeF just like domestic invoices. Because the foreign recipient cannot log into KSeF, delivery happens outside the platform (via email, EDI, etc.) with the KSeF QR code included for verification.
</Note>

To automatically import invoices received by your suppliers from KSeF, continue with the [KSeF receiving invoices guide](/guides/pl-ksef-receiving).

## GOBL addon reference

Detailed information about the FA(3)-specific extensions and validations can be found in:

* [Poland FA(3) VAT v3 Addon Documentation](https://docs.gobl.org/addons/pl-favat-v3)
* [Poland Tax Regime Documentation](https://docs.gobl.org/regimes/pl)

You can also use the [GOBL Builder](https://build.gobl.org) to create custom invoices with the Polish regime and FA(3) addon.

## FAQ

<AccordionGroup>
  <Accordion title="What happens when I send an invoice to a foreign recipient?">
    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.
  </Accordion>

  <Accordion title="What's the difference between test, demo, and production environments?">
    **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.

    <Tip>
      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.
    </Tip>
  </Accordion>

  <Accordion title="What KSeF applications and portals are available?">
    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
  </Accordion>

  <Accordion title="How do I configure my workspace for Polish invoicing?">
    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.
  </Accordion>

  <Accordion title="I get a &#x22;failed to create session (Status 403 Forbidden)&#x22; error when sending an invoice to KSeF. What does it mean?">
    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).
  </Accordion>

  <Accordion title="Where do I find Poland-specific GOBL documentation?">
    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.
  </Accordion>

  <Accordion title="How do I set the unit of measure (jednostka miary) on a line item, like &#x22;szt.&#x22; or &#x22;usł.&#x22;?">
    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"
    }
    ```

    <Note>
      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.
    </Note>
  </Accordion>
</AccordionGroup>

More available in our [Poland FAQ](/faq/poland) section

***

<AccordionGroup>
  <Accordion title="🇵🇱 Invopop resources for Poland">
    |            |                                                                                                                                                                                                                                                      |
    | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Compliance | <Icon icon="https://assets.invopop.com/flags/pl.svg" /> [Invoicing compliance in Poland](/compliance/poland)<br /> <Icon icon="timeline" /> [Compliance timeline](/timelines/poland)                                                                 |
    | Apps       | <Icon icon="https://assets.invopop.com/flags/pl.svg" /> [Poland](/apps/poland)                                                                                                                                                                       |
    | Guides     | <Icon icon="book" /> [Supplier registration](/guides/pl-ksef-supplier)<br /> <Icon icon="book" /> [Issuing invoices](/guides/pl-ksef)<br /> <Icon icon="book" /> [Receiving invoices](/guides/pl-ksef-receiving)                                     |
    | FAQ        | <Icon icon="square-question" /> [Poland FAQ](/faq/poland)                                                                                                                                                                                            |
    | GOBL       | <Icon icon="https://assets.invopop.com/icons/gobl.svg" />  [Poland Tax Regime](https://docs.gobl.org/regimes/pl)<br /> <Icon icon="https://assets.invopop.com/icons/gobl.svg" /> [Polish KSeF FA(3) Addon](https://docs.gobl.org/addons/pl-favat-v3) |
  </Accordion>
</AccordionGroup>

<Card title="Participate in our community" icon="forumbee" href="https://community.invopop.com" arrow="true" horizontal>
  Ask and answer questions about invoicing in Poland →
</Card>