KSeF: Poland's e-invoicing API will break your store. Here is where

Rostislav Havryliuk — Wed, 23 Sep 2026 11:22:59 +0000

Poland made B2B e-invoicing mandatory. Biggest companies from 1 February 2026, everyone else from 1 April 2026. Invoices to companies now go through KSeF, a government system. Not a PDF you email. An XML the state accepts or rejects.

Two dates that get lost in summaries. Receiving invoices through KSeF is mandatory for everyone from 1 February 2026, the April deferral covers issuing only. So your purchase invoices have to be pulled from the API earlier than you have to push your own. And until the end of 2026 the smallest sellers can stay outside: invoiced sales of 10,000 zł gross or less per month, lost from the invoice that crosses it. B2C sales and receipts do not count toward that threshold. (dates and legal basis, Ministry of Finance)

I integrate stores and SaaS with this. Here is what actually breaks. Facts below are current as of September 2026, KSeF 2.0 API.

Most of your invoices do not go there

B2C invoices are voluntary. The Ministry says so in its own FAQ. Mandatory means invoices to companies. The trigger is one field: the buyer's tax ID, the NIP. (Ministry FAQ)

Neither Shopify nor Stripe collects it by default. Stripe Checkout has tax ID collection and supports Polish VAT numbers, it is just off unless you turn it on. Shopify exposes tax IDs in B2B and through checkout customisation. Either way somebody has to enable it, map it, and decide what happens when it is missing.

So the first question is not "which API". It is "does our checkout ask for a NIP, where does it land, and what do we do when a customer asks for a company invoice after the order". Answer that first.

Out of scope too: OSS and IOSS, pro formas, internal notes, fiscal receipts with a NIP up to 450 zł until the end of 2026.

Do not call the API per order

The rate limit docs describe an online store as a separate case. The recommendation: collect invoices and send them in batches, for example every 5 minutes. (API limits, CIRFMF/ksef-api)

That answers most limit questions. Numbers as published in September 2026:

1 MB per invoice
10,000 invoices per session
50 ZIP files per batch, 100 MB per package before encryption
interactive sending: 10/s, 30/min, 180/h
over the limit: 429 plus Retry-After, and the block grows if you keep pushing

Limits count per (context, IP). Test runs roughly 10x higher than production, which is why this surfaces after launch. Check the current numbers in that repo before you size anything, they move between API versions.

Also: the retrieval API is for syncing to your database. Polling faster than every 15 minutes gets you blocked. So does fetching invoices one by one instead of using export.

Midnight will flip your invoices into offline mode

If the issue date P_1 is earlier than the day KSeF accepts the file, the invoice becomes "offline24" automatically. You did not set a flag. It just happens. Now you owe a send deadline. (automatic offline mode)

Worse: batch sessions count the moment the session opens, interactive sessions count the moment each invoice is sent. A batch opened at 23:59 saves the day. An interactive one does not.

Run your nightly job at 2am, not at midnight.

Retries create second invoices

KSeF blocks duplicates on three fields: seller NIP, document type, invoice number. Duplicate comes back as 440. Uniqueness holds for ten years. (invoice verification)

This saves you on retries. On one condition: the invoice number must be stable.

Generate the number at send time and a retry makes a new one. KSeF sees two different invoices. Two KSeF numbers. Two live invoices for one order. The only fix is a credit note to zero.

There is no idempotency key in the API. Build it yourself:

persist the invoice number with the order before the first send
store the SHA-256 of the XML, computed before encryption
read the session status before any retry, including the list of rejected invoices

Out-of-order numbering is fine, by the way. The Ministry says so directly. A rejected invoice sent later does not need a correction.

Your queue is not FIFO

A credit note must carry the KSeF number of the original. So a credit note for an offline invoice waits until the original gets its number.

Same-day refunds are normal in e-commerce. Your queue needs that dependency, or it will fail in week one.

Two more:

correction notes are gone since February 2026, everything goes through the seller
there is no cancel; wrong buyer NIP means credit note to zero and a new invoice

Rejected means it never existed

No invoice, no number, nothing in the records. You cannot correct it. You send a fixed file.

In your system the order looks invoiced. The customer waits for a document that does not exist. If rejections only go to a log, nobody notices for a week. Send them to a human.

KSeF checks the schema, UTF-8 without BOM, the issue date not being in the future, the NIP checksum (production only, so this one survives your tests), sizes and hashes.

It does not check your math. Wrong totals get accepted.

Offline modes: one flag, four deadlines, and two QR codes

Mode	Triggered by	Send by
offline24	you, no reason needed	next business day
unavailability	KSeF	next business day after it ends
failure	KSeF	7 business days after it ends
total failure	minister	no obligation

The mode itself is one boolean in the request. The deadline math is yours.

The part that is not one boolean is the visualisation. Any invoice used outside KSeF needs a QR code, and an offline invoice needs two: KOD I, which encodes the verification URL, issue date, seller NIP and a hash of the file, and KOD II, which proves you issued it, and which has to be signed with a KSeF certificate. Once the invoice reaches KSeF, you are back to one code with the KSeF number under it. (QR codes)

So offline support means: requesting and storing a certificate, signing locally, and rendering one or two codes depending on state. Budget for it separately.

In 2026 the Ministry did not declare a single KSeF failure. Go-live pain was in the national login services.

Small stuff that eats a day

buyer NIP in the wrong field means the buyer never sees the invoice, even though it was accepted
the KSeF number is 35 chars with a checksum, validate it locally
the XML is the invoice, the PDF is a picture of it
access tokens live minutes, the auth challenge expires in 10
product names go into XML as they are, so your HTML entities will break the file

The currency trap

There was supposed to be a KSeF-specific exchange rate rule. It was repealed before it came into force. The general rule still applies.

But the consolidated text of the VAT act was published before the repeal, so the dead rule is still printed there as future law. Plenty of articles repeat it.

If someone shows you a "new KSeF rate rule", check their date. And confirm your case with a tax advisor, not with a blog post.

Penalties

Statutory start is January 2027. In September 2026 the Ministry announced a deferral to the end of 2027, and that announcement says a law still has to be written. (Ministry announcement, 16 September 2026)

So: not a fact yet. The obligation to use KSeF was never deferred.

If you are an agency outside Poland

A Polish VAT number alone does not put your client in scope. What matters is a seat or a fixed establishment in Poland taking part in the transaction. The Ministry published guidance on that in January 2026 and still asks for case-by-case assessment.

Budget it as real work: collect a NIP, keep numbers stable, own a queue with retries and dependencies, surface rejections, handle offline QR, write the KSeF number back to the order.

If you are wiring a Shopify, WooCommerce or Stripe setup to KSeF and you hit one of these, write to me and I will tell you what it takes: polaczone.pl. The Polish version of this guide, with the same sources, is here.

DEV Community: Rostislav Havryliuk