ZATCA’s e-invoicing programme changes the life of a receipt in Saudi Arabia. A sale is no longer only a line on a till report. It has to become an e-invoice with a defined shape, a cryptographic stamp, and a response from the platform. Teams that bury that work inside the cashier screen usually discover the problem during a Friday queue. This article separates the till from the gateway, which is also how Codex E-Invoice is being built.
Two different jobs
The till’s job is to sell: identify the item, apply the price, take the tender, print what the customer needs and keep a local record. The e-invoicing job is to represent that sale in the form ZATCA expects, submit it on the path that applies to the taxpayer, and store the acceptance or the rejection. Mixing the two jobs means a timeout at the tax platform becomes a timeout at the drawer.
A gateway is the boundary. The retail checkout emits a completed sale. The gateway maps it, signs what must be signed, submits it, and writes the status back in language a manager can read. Codex E-Invoice is that gateway, and it is in development. This article is an engineering briefing, not a certificate.
What “Phase 2” changes for a counter
The integration phase is stricter than generating a PDF that looks like an invoice. The taxpayer’s solution has to talk to the e-invoicing platform, and the onboarding of that solution is a process with the authority, not a library you enable in a config file. A retail checkout vendor who says “we support ZATCA” should be able to say which path, for which taxpayer, and what the cashier sees when the platform rejects a document.
Rejection is a normal case. A missing field, a wrong VAT category, or a clock skew should produce a visible failed invoice with the reason, and a way to correct and resubmit. A design that only logs the error has not finished the feature.
- Name the integration path
- Show a rejected invoice to a manager
- Keep the reason next to the sale
- Do not treat onboarding as a software setting
What the retail checkout should finish before the gateway
The sale needs a stable identity, the seller and buyer fields you actually have, line items with the right tax category, the totals the customer paid, and the time the sale closed. If the cashier can still edit the ticket, it is not ready to invoice. Offline tills add a sequencing problem: invoices may be created while the shop is offline and submitted later, in an order the gateway must preserve. Design the local sequence before you design the HTTP client.
Currency and language belong here too. A till selling in SAR, with an Arabic receipt and an English cashier UI, still has to send one consistent invoice. Pretty UI text and the legal document are not the same string.
What the gateway should own
Cryptographic material, the call to the platform, retries, and the archive of request and response belong to the gateway. Retries must be safe. Submitting the same invoice twice because the first response was slow is a compliance incident, not a glitch. Store the payload you sent, the hash you computed, and the body you got back. When someone asks why a document was cleared or rejected three months later, the answer should be a record, not a memory.
Keep the cashier out of this screen. Give the manager a queue: queued, accepted, rejected. Let them open the rejection reason without an engineer.
Certification, sandbox and honest status
A sandbox call is not a production clearance. A library that can build XML is not an onboarded e-invoicing solution. If you are procuring this, ask for the onboarding status of the taxpayer’s device or solution, the environment the demo used, and who is accountable when ZATCA changes a validation rule. Codex Thrill will not describe Codex E-Invoice as live or certified while it is still in development.
The practical next step for a retailer is a sample of real tickets: a simple taxable sale, a discount, a refund, and a sale that was taken offline. Map those four through the gateway on paper before anyone estimates an integration in days.
How this sits next to Codex Retail
Codex Retail already completes the sale on the Ubuntu kiosk, in English or Arabic, in EUR, USD or SAR, and syncs tills when the link returns. e-invoicing is the neighbouring service, not a modal on that kiosk. Sales that need a Saudi e-invoice leave the till as a completed ticket and enter the gateway. Other countries do not pay the cost of that path. That split is the whole design.
Conclusion
Treat e-invoicing as a gateway with a status, an archive and a person who can read a rejection. Leave the cashier on the local sale. Certification is a process with ZATCA for a specific taxpayer solution, and it should be stated only when it is true. Codex E-Invoice is being built to that boundary, and it is not finished.
Frequently asked questions
Should the cashier wait for ZATCA before the receipt prints?
No. Finish the sale locally. Submit the e-invoice from a gateway and show the result to a manager. A tax timeout should not freeze the lane.
Is Codex E-Invoice already ZATCA certified?
No. It is in development. Onboarding and certification belong to the taxpayer’s solution and are not claimed on this website.
What should we archive with each invoice?
The payload you sent, the hash, the platform response, and the link back to the retail checkout ticket. You will need them when a document is questioned later.
Which sales should we use as a test pack?
A standard taxable sale, a discounted sale, a refund, and a sale captured while the shop was offline. If those four map cleanly, the integration is real.
