A conversation about KSeF, Poland’s national e-invoicing system, in an online store almost always starts with the question “which plugin should we install”. A question about a tool, asked at a moment when nobody has answered the questions about the process yet. From my perspective, as someone who has been connecting stores with financial systems for years, the plugin is the last piece of that puzzle. Not the first. And the things that cost the most later come from decisions made long before anyone touched a line of integration code.
Table of contents
A plugin is an interface, not an invoicing process
A store extension will build the document and send it to the gateway. Fine. It just does not settle when that document should be created at all, and that is the whole point of the rollout. In e-commerce, placing an order, booking the payment and releasing the goods are three separate events, spread out in time and carrying completely different risks.
The most common mistake? The store issues an invoice the moment the order is placed, the transfer never arrives, and a document that needs correcting is already sitting in the records. The other extreme, invoicing only after shipment, can throw accounting periods out of line for orders placed around the turn of the month.
The sensible decision is to define the invoicing trigger in the business logic layer, on the server side, with the exceptions written out explicitly: prepayment, cash on delivery, deferred payment, partially fulfilled order. The plugin settings then mirror that decision instead of making it for us. Only at that stage does integrating your store with KSeF stop being a matter of configuration and become a matter of design.
Customer data: how is the store supposed to know who it invoices
The system handles trade between businesses, and consumer sales follow a different logic. The store has to separate those paths already at the cart level, before the customer clicks “place order”. Attaching a tax identification number to a closed order is a straight road to errors and corrections.
A NIP field in the form on its own? Not enough. You need format and checksum validation, a country check, plus consistency with the rest of the address data, because a customer entering a company number next to a private delivery address is an everyday occurrence. Add foreign customers, EU VAT numbers, the OSS procedure and marketplace sales. Every one of those mappings adds its own share.
A separate topic, usually badly underestimated: accounts created years ago, with incomplete or outdated data. During migration they have to be completed, flagged or deliberately excluded from automatic invoicing. Otherwise the automation will generate a pile of documents that nobody will be able to defend later.
KSeF in e-commerce and the systems you already run
The store is rarely the only place where an invoice is created. Next to it there is a warehouse, an ERP, an invoicing program and an accounting office, and each of those systems has historically been allowed to issue a document. Once the central system is connected, that multitrack setup stops being a minor inconvenience and turns into a real risk.
The classic rollout failure is a double submission. The same document goes to the gateway from the store and from the warehouse system, because nobody decided who the source of truth is. It usually surfaces after the fact, while reconciling sales for the period. There is no way around the same question in projects such as integration with Subiekt and Optima, where document numbering has to have a single owner.
The architectural decision sounds trivial and hurts organizationally: one point where documents are issued, all the other systems only consume the number and the status. The integration is best built on an event queue rather than a synchronous call, because finalizing an order cannot wait for a response from an external gateway. The customer has to see the purchase confirmation regardless of what happens next in the background.
Outages, limits and security on the server side
The gateway is sometimes unavailable, and the store cannot suspend sales because of it. What you need is a durable document queue, retries with a growing interval and a clear “waiting to be sent” state, visible to the support team and not only in a technical log somewhere on the server.
What actually needs monitoring
- documents sitting in the queue longer than an agreed threshold,
- documents rejected during structure validation, with the error message stored,
- tokens, certificates and sessions approaching expiration,
- the delay between creating an invoice and it being assigned a number in the system,
- a mismatch in the number of documents between the store and the financial system for the same period.
Without alerts, every one of these problems only shows up at the month-end close. In other words, when the fixes are the most expensive and get done under time pressure.
Credentials in a publicly available application
Access to the system means real permissions over the company’s documents. Keeping it in the options table, in plain text, is a time bomb. A store is an application exposed to the world and scanned every day, a completely different risk profile than an internal ERP tucked away behind a firewall.
A sound pattern moves credential handling to an intermediate layer, in a trusted environment. The store then publishes only the business event and knows no secrets at all. With heavier traffic and more elaborate logic, this sometimes ends in a decision to migrate to a custom backend. Log retention and document archiving are designed separately, because those are requirements no plugin will take care of for anyone.
Corrections, returns and complaints, the daily reality of a store
A product return in online sales is the norm, not an incident. That being so, issuing correcting documents has to be automated to exactly the same degree as issuing invoices. Otherwise all the savings from automation land on the accounting desk.
A correction refers to the number of the original document, so that number has to be permanently linked to the order in the store’s database. Not in the integration log, which will be rotated after a month. I have seen this a few times – the gap only reveals itself with the first serious return, and by then it is already unpleasant.
Partial returns, product exchanges and discounts granted after the sale require mapping the order line items, not just the total amount. I recognize a failed rollout by one symptom: corrections are made by hand in another program and never come back to the store. The data in both places then starts to live a life of its own.
The cost structure of the rollout and of maintenance
The plugin license is the smallest item here and at the same time the most loudly discussed one. The budget is driven by three other things: the number of systems to connect, the quality of the historical data, and the number of exceptions in the sales process, meaning everything that deviates from an ordinary order paid up front.
Maintenance costs money in the rhythm of change, not evenly. Document schema updates, changes to the gateway interface, store migrations, payment gateway swaps, updates of the plugins themselves – each of those can disturb the integration exactly when nobody expects it.
That is why a test environment and a repeatable, reproducible deployment are not a luxury but a way to keep a single change from stopping sales for several hours. And the biggest hidden cost still remains the manual work of the accounting team in a situation where the automation handles the happy path only and every deviation falls on people.
Summary: the plugin at the end, not at the beginning
The order that works is the opposite of the intuitive one. First a map of the sales process and a decision on the source of truth for documents, then the design of the integration and of error handling, and the specific tool is picked last, once it is clear what it has to do.
The signs that a project is heading the wrong way show up early: nobody owns the process on the business side, there is no monitoring or alerting, corrections are created outside the system. Every one of those symptoms can be fixed. It is simply cheaper to do it before launch than after the first month-end close.
At Web Systems we have been designing integrations, automations and B2B systems around online stores since 2006. If you are planning an online store implementation, cleaning up your document flow or thinking about modernizing your store and the systems around it, write to us and let’s talk about the scope.
