The question we ask earliest on any clearance project is the one teams defer longest: what happens when the platform is down? When the tax authority sits in your send path, its outage is your outage — invoices you cannot issue, deliveries you cannot make, a queue that grows while support tickets pile up. The regimes that thought about this define an offline mode; the ones that did not leave you to improvise during an incident. Either way the resilience is yours to build. Here is how.
1. Why an outage is different under clearance
In an exchange model, if a network hop fails you retry and the invoice is a little late. Under clearance the authority's response is part of the invoice's legal validity, so an outage does not just delay delivery — it can stop you issuing a valid document at all. Sales that depend on an invoice (goods that cannot ship without one, a customer who will not pay without a cleared invoice) stall with it. The blast radius reaches from your integration into the warehouse and the ledger.
That is why "the platform was down" is not an acceptable answer to an auditor or a customer, and why the recovery procedure has to be designed in advance, not discovered at 2am.
2. Three ways a regime handles downtime
Regimes fall into three broad camps, and which one you are in dictates your whole contingency design.
| Camp | What the rules allow | Example |
|---|---|---|
| Defined offline mode | Issue in a contingency mode during downtime, then upload afterwards within a stated window; the document is valid meanwhile | Poland's KSeF has several: the voluntary "Offline24" (upload by the next business day) plus longer windows when the authority declares an outage |
| Platform resilience, limited contingency | The authority runs redundancy and publishes status; narrow contingency provisions exist but issuing is expected to go through | Italy's SdI, which processes asynchronously and returns receipts |
| No offline path | No valid document without a live response — if the service is unreachable you cannot issue, full stop | India's IRP: no IRN, no valid tax invoice |
The camps demand different builds. A defined offline mode means you must implement the contingency issuing path and the deferred-upload reconciliation — it is extra work, not a free pass. "No offline path" means your resilience budget goes into buffering, alerting and customer communication, because you cannot manufacture validity locally. Read the rule precisely: an offline allowance usually comes with conditions (a locally generated number, a QR code, a hard upload deadline) that are themselves compliance obligations.
Poland shows how much hides in that detail. What looks like one "offline" feature is really three clocks: the voluntary Offline24 mode requires upload by the end of the next working day, but a formally declared KSeF failure grants up to seven working days, and a scheduled unavailability one working day. Which window you get depends on whether you chose to work offline or the platform forced you to — so your contingency logic has to know which situation it is in, not just that it is offline.
The trap in "offline is allowed"An offline mode is a second issuing path with its own rules, not a relaxation of the first. If you only build the online path and plan to "fall back to offline", you have not built the fallback — you have named it. The upload-afterwards step, the deadline and the identifier handling are all real code.
3. Idempotency: the retry that must not duplicate
Outages rarely present as a clean "service unavailable". They present as timeouts — you sent the invoice, and you do not know whether it arrived. The naive reaction is to retry, and the naive retry is how you clear the same invoice twice, land two identifiers on one transaction, and spend the next audit explaining phantom sales.
The defence is idempotency, and it has two halves:
- A stable client-side key per document. Generate a unique reference for the invoice once, before the first attempt, and send it on every retry. If the platform supports idempotency keys or dedup on your document number, a retry becomes a no-op that returns the original result instead of creating a new one.
- Query before you re-send. Where the platform offers a status lookup, a timeout should trigger a query ("what happened to document X?"), not a blind re-submit. You resubmit only if the query confirms the authority never saw it.
This is unglamorous plumbing and it is the single highest-value thing you can build for a clearance integration. Duplicate clearances are far harder to unwind than a late one.
4. The state everyone forgets: "unknown"
Most integrations model two outcomes — success and failure. Clearance has a third that dominates during an outage: unknown. You sent it; the connection dropped; you have no response. The document is neither confirmed nor confirmed-failed.
"Unknown" needs to be a first-class state in your data model, with its own behaviour: it is not retried blindly (see idempotency), it is not shown to a user as "sent", and it is resolved by reconciliation rather than by guessing. A system that collapses "unknown" into "failed" will re-issue documents that actually cleared; one that collapses it into "sent" will quietly ship non-compliant invoices. Give it its own status and a job that chases it to resolution.
5. A resilient pattern
The shape that survives contact with a real outage is a transactional outbox with asynchronous confirmation:
- Persist first. Write the invoice and a stable idempotency key to your own store before you call the platform. Nothing is "in flight" that is not first durable locally.
- Submit asynchronously. A worker drains the outbox. It never blocks the user-facing transaction on the authority's response.
- Confirm by polling or callback. Move documents from awaiting to cleared/rejected on the authority's response; leave timeouts in unknown.
- Reconcile relentlessly. A scheduled job re-queries every awaiting and unknown document until the platform gives a definitive answer. This job is your outage recovery — when the platform returns, it drains the backlog by itself.
- Trigger the contingency path by rule. If the regime has an offline mode and the outage crosses your threshold, switch issuing to it deliberately, and let the same reconciliation job handle the mandated later upload.
- Monitor and communicate. Alert on backlog size and age, not just on errors, and have a prepared line for customers waiting on invoices.
Everything here decouples the customer-facing act of invoicing from the authority's availability, which is the only way to keep selling while the platform is down.
6. What to ask of every clearance regime
Before you design, get these answered from the primary specification — the answers change the build materially:
- Is there a defined offline / contingency mode? If so, exactly how is a document issued in it, and what makes it valid meanwhile?
- What is the upload deadline after downtime, and what identifier must the offline document carry?
- Is there a status-query API so a timeout can be resolved without re-submitting?
- What are the penalties for late transmission versus for a genuinely missing document — they are usually different.
- Does the authority publish a status page or maintenance calendar you can build alerting against?
These map onto question seven — "what happens when it fails?" — from our guide to reading a new country mandate, and they are the difference between a clearance integration that degrades gracefully and one that becomes an incident every time the platform sneezes. Poland's Offline24 provisions, Italy's SdI receipts and India's IRN hard-stop each imply a different answer; the Poland, Italy and India pages note where each stands.
- Under clearance, the authority's outage is your outage — and can stop you issuing a valid invoice at all.
- Know your camp: defined offline mode, platform resilience, or no offline path. Each demands a different build.
- Idempotency is non-negotiable — a stable key and query-before-resend stop duplicate clearances.
- Model "unknown" explicitly. It is neither success nor failure and it is where outages park your documents.
- Outbox + async confirmation + a relentless reconciliation job is the pattern that drains the backlog on its own when the platform returns.