KSeF E-Invoicing for WooCommerce — FA(3) e-invoices to Poland’s KSeF straight from orders

KSeF E-Invoicing for WooCommerce is a plugin for shops in Poland that invoice businesses. Since 2026 Polish VAT payers issue B2B invoices through the National e-Invoice System (Krajowy System e-Faktur, KSeF). The plugin turns a WooCommerce order into a structured invoice in the official FA(3) format and sends it straight to the KSeF API 2.0 — no accounting SaaS in the middle and no monthly subscription. The KSeF number and the official confirmation of receipt (UPO) are saved on the order.

What you need. A KSeF token for your company’s NIP, generated in the KSeF taxpayer application (Aplikacja Podatnika KSeF) of the chosen environment (“Tokeny”, permissions to issue and view invoices). Honestly about testing: the plugin has been tested on the official KSeF TEST environment of the Ministry of Finance — the invoices were accepted with real KSeF numbers and UPOs, and every XML is valid against the official FA(3) XSD. We have not run it on DEMO or PRODUCTION yet: the API is the same, but it needs a real company. Try it on your own NIP in the 7-day Pro trial — if KSeF answers differently than on TEST, we fix it quickly.

The shop remains responsible for the content of its invoices: the plugin builds FA(3) from the WooCommerce order data (rates, addresses, NIP). Tax decisions — when to use 0 % KR, WDT or EX, the cash method, the correction type — follow the schema field descriptions and the Ministry of Finance documentation; show your settings to your accountant before switching to PRODUCTION.

What the customer sees

The checkout gets a “NIP (for a VAT invoice)” field. It is optional: without a NIP the order goes through as usual and no KSeF invoice is created. When a NIP is entered, the plugin checks its checksum — a wrong number stops the order with an explanation. “5265877635”, “526-587-76-35” and “PL5265877635” are all accepted.

WooCommerce 11 hides the “Company” field by default, so the invoice would go out in a person’s name. While the WooCommerce field is hidden, the plugin shows its own “Company name (for a VAT invoice)” field next to the NIP: it is required together with a NIP, and the company name goes on the invoice as the buyer. Switch the “Company” field on in the WooCommerce settings and the plugin uses that one instead.

What the admin gets

• WooCommerce → KSeF: “Invoices”, “Settings” and “Licence” tabs.
• The KSeF token is stored encrypted in the database with keys derived from your site’s secret salts; the form shows only its last characters. It can also be defined as CCKSEF_TOKEN in wp-config.php.
• “Check the connection to KSeF” runs the full authentication and tells you which NIP and environment it works with, or shows the KSeF error in its own words (for example 450 for a wrong token).
• Environment — TEST, DEMO or PRODUCTION; while TEST or DEMO is on, a reminder at the top says that invoices have no legal effect.
• Seller (Podmiot1): NIP, name, address, contacts, KRS / REGON / BDO in the invoice footer.
• Numbering: a format such as FV/{YYYY}/{MM}/{N}, reset monthly, yearly or never, separate counters per environment; numbers already used are skipped.
• VAT: from WooCommerce taxes, a fixed rate included in prices, or a VAT-exempt seller (zw with the legal basis).

• Invoice register: number, order, buyer with NIP, total, status, KSeF number or rejection text; status filter and search.
• “KSeF invoice” box on the order: invoice number, status, KSeF number, QR code, links to details, XML and UPO. Orders without an invoice get an “Issue KSeF invoice” button.
• Order notes: “created and queued”, “accepted, KSeF number …” or the rejection reason.
• “Send queued invoices now” sends the queue at once, including invoices waiting for a retry.

A rejected invoice shows up right away: in the register, on the order and in a notice at the top of the admin. Next to it is the KSeF text in Polish, exactly as the Ministry of Finance returned it, and the full FA(3) XML. After a fix (date, buyer data, rate) — “Regenerate and send”; an invoice that never reached KSeF is cancelled with “Discard”.

The number is already taken by another program. If you also issue invoices in another program on the same NIP with the same number pattern, KSeF refuses a second invoice with that number. The plugin compares files by SHA-256 against the original’s UPO: its own file (for example when a KSeF answer was lost) is accepted with its KSeF number, someone else’s never. Such an invoice becomes “Rejected by KSeF” with an explanation and the KSeF number of the other document; change the number format (for example a SKLEP/ prefix) and click “Regenerate and send” — the invoice gets a new number.

How it works — step by step

1. Setup. WooCommerce → KSeF → Settings: environment, seller NIP and address, KSeF token, “Check the connection to KSeF”.
2. Checkout. A business buyer enters the NIP (and the company name if the “Company” field is hidden). A wrong NIP does not pass.
3. Order status. The order becomes “Completed” (or “Processing” — your choice) — the plugin builds the FA(3) invoice with the next number and queues it.
4. Sending. Action Scheduler opens a KSeF online session right away, encrypts the invoice and sends it; a cron every 5 minutes is the safety net.
5. KSeF status. The plugin polls KSeF: accepted — the KSeF number lands on the order and the UPO follows a minute or two later; rejected — the reason text appears in the register and on the order.
6. Outages. KSeF unreachable, 429 or 503 — the invoice waits and retries by itself; the same XML byte for byte, so no second invoice appears.
7. Refunds (Pro). A WooCommerce refund by items or by amount creates a KOR correction invoice with the original’s KSeF number; it waits until the original has its number.
8. Customer (Pro). The “Your invoice is in KSeF” e-mail with the KSeF number and the KOD I QR code, a block in My Account and a printable invoice.

Under the hood

• FA(3), schema 1-0E — element order strictly by the Ministry of Finance XSD; eight document types (B2B with several rates, zw, EU in EUR, B2C, export, KOR with and without a KSeF number, minimal) validate against the official schema.
• KSeF API 2.0 without third-party libraries: token authentication (RSA-OAEP SHA-256), online session of up to 20 invoices, AES-256-CBC, status polling, UPO. Access and refresh tokens are cached; 401 — re-authentication, 21470 (Ministry key rotation) — the keys are re-read.
• The XML never changes after it is created. A retry sends the same file byte for byte, so a lost KSeF answer yields 440 with the original number rather than a second invoice.
• A 440 duplicate is accepted only for the plugin’s own file: SkrotDokumentu from the original’s UPO is compared with the SHA-256 of our XML. If it cannot be compared — retries for up to 24 hours, never “accepted blindly”.
• Numbering under a lock (MySQL GET_LOCK): two orders in the same second never get the same number.
• NBP rate (Pro) — table A of the last working day before the sale date; the XML carries KursWaluty and VAT in PLN (P_14_xW).
• Printable invoice (Pro) — an informational copy: for an invoice in EUR the print does not show the VAT amount in PLN; it is in the XML sent to KSeF.
• KSeF offline modes (offline24, emergency, KOD II) are not implemented: while KSeF is unavailable, invoices wait in the queue.
• Deleting the plugin removes the token, the token cache and the cron jobs; the invoice register and counters stay, so numbering continues after a reinstall. The CCKSEF_DELETE_DATA constant removes everything.

Installation

1. Plugins → Add New → Upload Plugin: choose ksef-e-invoicing-for-woocommerce-1.0.1.zip and activate.
2. WooCommerce → KSeF → Settings: switch “Issue KSeF invoices” on, choose the environment (start with TEST), fill in the seller NIP, name and address.
3. Generate a token in the taxpayer application of the same environment, paste it and click “Check the connection to KSeF”.
4. Check the WooCommerce tax rates and the number format (give the shop its own prefix if another invoicing program is in use).
5. Place a test order with a NIP and set it to “Completed” — within a minute the order shows a KSeF number.
6. Moving to PRODUCTION — switch the environment and paste the PRODUCTION token.
7. For Pro: paste the licence key from the purchase e-mail or start the 7-day trial.