Production Environment (ZATCA E-Invoicing)

This guide is aimed at developers and technical integration teams who have finished the testing phase and are preparing to run their live invoices within e-invoicing in Saudi Arabia. Its subject is one specific thing: the Production Environment, the live environment in which you issue invoices that carry real tax and legal effect before the Zakat, Tax and Customs Authority (ZATCA).

We separate here what belongs to Production from what does not. The Sandbox environment and how to test before moving on have their own standalone guide in CSID certificate and the Sandbox guide. The details of the APIs themselves (endpoints, headers, and request shapes) are covered in the guide to API integration with the Fatoora platform. This guide assumes you have read that, and focuses on the live environment alone.

The Production Environment is not another copy of the test environment under a different name. It is an environment with stricter operating rules, a different certificate (the Production certificate, PCSID), and invoices that cannot be undone once cleared. Every mistake here leaves a mark in ZATCA’s records, so preparing for it differs fundamentally from freely experimenting in the Sandbox.

In this guide we go over the definition of the Production Environment, the Production certificate (PCSID) and how it differs from the Compliance certificate, real invoices and their legal effect, the two paths of instant Clearance for business-to-business invoices and 24-hour Reporting for consumer invoices, then the migration process from Sandbox to Production, and finally monitoring and service-level management after go-live.

What exactly is the Production Environment?

The Production Environment is the live gateway of the Fatoora platform that receives your actual invoices and clears them before ZATCA. Every invoice that passes through here is treated as an official tax document: it enters ZATCA’s records, is counted in your tax return, and legally binds you toward the buyer and the regulator.

This definition is the fundamental difference from the Sandbox. In the Sandbox you send as many test invoices as you like with no effect, because the environment is designed to absorb your errors and train your system. In Production there is no undo button: a cleared invoice stays in the record, and any correction requires issuing a subsequent credit or debit note rather than deleting the original.

The Production Environment runs on a network path completely separate from the Sandbox, with a different Base URL. Mixing the two URLs is one of the most dangerous common mistakes. Sending a Production invoice to the Sandbox URL means it was never actually cleared, and your team may believe everything is fine while nothing sent has any tax effect, so the fault surfaces late when the record is reviewed.

For this reason, mature integration systems handle an explicit environment variable (such as APP_ENV) that determines the Base URL and the certificate file used. Do not leave the URL as a value hard-coded inside the code; make it a single clear option that is switched when moving to Production, so no partial switch sends some requests to one environment and others to another.

The useful mental model here: the Sandbox is for the compliance and training phase, and the Production Environment is for real operation. Do not issue a live invoice before your system has passed every compliance case in the Sandbox, and do not test a new scenario directly in Production. This discipline is the first line of defense against errors with tax effect.

Isolating the two environments must extend to your data and your certificates together. Store the Production certificate in a separate vault from the Sandbox certificate, and prevent any path in your system from mixing them. Many first Production incidents happen because the system picked up the Sandbox certificate when signing a live invoice, so the signature was invalid for Production even though the invoice was well-formed. Strict separation of the two environments’ secrets guards against this class of error.

Remember too that the Production database must not become mixed with test data. The test invoices you issued during integration have no place in the Production record, and must not leak into your actual financial reports. Start Production with a clean record, and keep test data in its own environment, so your live figures reflect your real business alone.

The Production Environment versus the Sandbox in one line

In short: the Sandbox is an environment with no effect; it tolerates your mistakes, reissues certificates freely, and is used for testing and initial integration. Production is a live environment where every invoice is an official document, its certificate is unique per device, and its errors are corrected with notes, not by deletion. Treat the move between them as a separate, planned event, not a passing change of a URL.

Production Environment

The move to Production is your device’s second digital-identity event, after compliance. In compliance, your device obtained a Compliance certificate (Compliance CSID) with temporary validity, whose purpose is to prove that your system generates well-formed invoices. When moving to Production, your device replaces that certificate with a Production certificate (PCSID), the identity with which it actually signs every live invoice.

This point is the most misunderstood. The Compliance certificate is not valid for Production, and the Production certificate is not issued until compliance is passed. The order is mandatory: successful compliance, then an issuance request, then receiving the PCSID, then starting live issuance. No step can be skipped, and any attempt to sign a Production invoice with a Compliance certificate is rejected at the gateway level.

The details of the Production certificate and the mechanism for issuing and renewing it have their own dedicated guide in PCSID certificate for Production. Here what matters to us is its operational role: it is the signing key that turns an XML document into a cleared invoice with legal value, and it is tied to one specific device and is not shared between devices.

Real invoices and their legal and tax effect

Every invoice issued from the Production Environment is a binding tax document. It carries the unique identifier (UUID), the cryptographic stamp signed with the Production certificate, the hash chain linked to the previous invoice, and the QR code. These elements together make the invoice verifiable for integrity and tamper resistance after issuance.

The hash chain in particular has an important operational effect in Production. Every invoice carries the hash of the invoice that preceded it on the same path, forming a continuous chain. Any gap or reordering in this chain reveals a fault. Your system must therefore reliably store the hash of the last cleared invoice and build it into the next one, even if the system crashes and is restarted.

The legal effect also means that correction has its own official path. If you issue an invoice with a wrong amount, do not delete it; instead issue a credit or debit note that references the original invoice by its identifier, passes through the same path, and is cleared in the same way. This preserves the integrity of the tax record and keeps the correction trail visible for review.

Invoice types in Production

The Production Environment handles two invoice types, each with a completely different path: the standard tax invoice between businesses (B2B), and the simplified tax invoice aimed at the consumer (B2C). The difference between them is not cosmetic; it determines the timing of your system’s interaction with ZATCA and when the invoice may be handed to the buyer.

The instant Clearance path for business-to-business (B2B) invoices

The business-to-business invoice is subject to the Clearance path. The governing principle here is that the invoice is not considered valid until ZATCA clears it in real time, and before that it may not be handed to the buyer. That is, clearance is a precondition for delivery, not a step that follows it.

The process sequence in Production is as follows. Your system generates the invoice XML document according to the UBL 2.1 standard, then signs it with the Production certificate (PCSID), then sends it to the clearance interface in the Production Environment, then waits for ZATCA’s instant response. ZATCA either clears the invoice, clears it with warnings, or rejects it with a reason.

Because this path blocks delivery of the invoice, it must be fast and reliable in Production. At a high-frequency point of sale, a delayed clearance response stalls completing the transaction in front of the customer. A mature system therefore designs a reasonable request timeout, limited retry logic, and a clear message for the employee when clearance cannot be obtained, instead of freezing the interface.

Handling the three response cases is essential. A cleared invoice is delivered to the buyer and recorded in your system in its final state. An invoice cleared with warnings is also delivered, but the warning must be logged and reviewed, because its repetition may later turn into a rejection. A rejected invoice is never delivered; your system corrects the cause and resends before any dealing with the buyer.

The most common rejection causes in Production relate to data correctness: a wrongly formatted tax registration number, a missing mandatory field, an inconsistency in tax calculation, or a fault in the hash chain. It therefore greatly helps for your system to validate the format of tax identifiers at the moment of entry, catching the error before building the invoice rather than after it is rejected.

There is a subtle difference specific to Production when retrying. If you send an invoice and no response reaches you due to a network interruption, the invoice may in fact have been cleared at ZATCA without your knowing. Resending the same document with its unique identifier may be treated as a duplicate. Retry in Production must therefore be governed by the invoice identifier: query the document’s status by its identifier before rebuilding it, rather than creating a new identifier for each attempt.

This behavior, known as idempotency, matters more in Production than in the Sandbox, because every duplicate issuance here pollutes the tax record with two invoices for a single transaction. Design the sending logic so that it separates building the invoice once from the attempts to deliver it to ZATCA, so the document stays fixed with a single identifier no matter how many network attempts recur.

The 24-hour Reporting path for consumer (B2C) invoices

The simplified invoice aimed at the consumer is subject to a completely different path called Reporting. Here the invoice is issued and delivered to the customer immediately without waiting for prior clearance from ZATCA, then your system reports it to ZATCA within a window not exceeding 24 hours from its issuance.

The operational difference between the two paths is decisive for designing your system. In Clearance (B2B), clearance comes before delivery, so the call to ZATCA is synchronous with the moment of sale. In Reporting (B2C), delivery comes before reporting, so the moment of sale can be separated from the moment of sending to ZATCA, batching invoices and sending them within the window. This suits fast points of sale that cannot tolerate waiting for ZATCA’s response on every transaction.

This separation is both an opportunity and a risk. The opportunity is that the customer’s payment experience is not affected by the response time of the network or ZATCA. The risk is that invoices accumulate in the reporting queue, so if the path fails for hours it may exceed the 24-hour window. Your system must therefore monitor the reporting queue and alert when an invoice is delayed beyond a safe time threshold shorter than the official window.

The simplified invoice in Production remains signed with the Production certificate (PCSID) and carries the QR code and the hash chain, exactly like the standard one. The difference is only in the timing of sending it to ZATCA, not in its structure or its signing requirements. You therefore build the simplified invoice in the same way, store it, and report it later within the batch.

In practice, a mature system designs a durable reporting queue that stores every simplified invoice the moment it is issued, and a periodic job that sends them to ZATCA and follows up on acknowledgment of receipt. On send failure, retry is automatic with the failure logged, and the invoice is not deleted from the queue until its reporting is confirmed successful, preserving the integrity of the record and the window.

Correcting invoices in Production: credit and debit notes

Because a Production invoice is not deleted, every correction goes through a credit or debit note. A credit note reduces the value of an original invoice, for example on a return or a later discount. A debit note increases its value, for example when correcting an undercharge in the calculation. Both are independent documents that reference the original invoice by its identifier, and pass through the same Clearance or Reporting path according to the type of the original invoice.

This means your system in Production must preserve the link between each note and the invoice it corrects. Issuing a well-formed note is not enough; it must carry the reference to the original precisely, otherwise it is rejected or loses its meaning in the record. Designing this link in advance saves a great deal at the first real return you receive after go-live.

Migrating from the Sandbox to the Production Environment

The move to Production (cut-over) is not a change of URL, but a planned process with a clear entry condition. The entry condition is your system passing every compliance case in the Sandbox without exception. Do not move a device to Production with a single untested compliance case, because Production errors leave a real tax mark that is hard to reverse.

The first step after compliance is switching the environment at the configuration level. Change the Base URL to the Production URL, switch the certificate file used, and make sure your system targets one environment only. The most dangerous thing here is a partial switch that sends some requests to one environment and others to another, so make the environment a single central value, not scattered values in the code.

The second step is issuing the Production certificate (PCSID) for each device. You request the certificate from the issuance interface in the Production Environment after passing compliance, receive the Production certificate, and store it securely tied to the device identifier. From this moment the device signs its live invoices with this certificate, not with the old Compliance certificate.

The third step is a first verification invoice closely monitored. Issue a real, limited-effect invoice and watch its full journey: signing with the Production certificate, calling Clearance or Reporting according to its type, receiving clearance, building the first link in the hash chain. The success of this invoice confirms that the transition happened at the level of certificate, URL, and logic together.

The fourth step is confirming that the hash chain starts from zero in Production. The Production hash chain is independent of the Sandbox chain, so the first Production invoice starts a new chain. Make sure your system does not carry an old Sandbox invoice hash into the first Production invoice, otherwise the chain breaks from its very start.

The fifth and final step is enabling monitoring before opening full operation. Do not scale up live issuance before you are sure the monitoring dashboards and alerts work and catch errors. A successful transition is measured by the first hundred monitored invoices, not by the first invoice alone.

The transition repeats for every new device

Note that the journey of compliance then Production is repeated in full for every new device. Opening a new branch or adding a point of sale means repeating the compliance steps and issuing an independent Production certificate for that device alone, without touching the devices already in operation. Design your setup flow so that it is self-restartable for each device, not a manual procedure executed once and its mechanism forgotten.

Monitoring and service-level management in Production

Mature integration does not stop at the first successful invoice. Production is a continuous operating environment that needs constant monitoring, because any interruption has a direct effect on issuing your invoices and meeting your deadlines. Monitoring in Production is not a luxury; it is part of your actual compliance.

Monitor first the success rate of Clearance and Reporting. A sudden rise in the rejection rate is an indicator of a fault in your system’s data or in a particular integration, and deserves an immediate alert. Track the ratio of cleared, cleared-with-warnings, and rejected invoices over time, because the trend matters more than the instantaneous number.

Monitor second the response time. In the Clearance path that blocks the user experience, a slowdown in the response stalls points of sale. Set an acceptable upper bound for the request time, and alert when it is exceeded persistently, because it may precede a full outage. In the Reporting path, monitor the age of the oldest invoice in the queue so it does not approach the 24-hour window.

Monitor third the certificate lifecycle. The Production certificate (PCSID) has a validity that expires, and missing the renewal date suddenly stops signing invoices. Set an alert ahead of expiry with enough lead time to renew or reissue the certificate, and handle the failure or replacement of any device by reissuing its certificate without affecting the rest of the devices.

Set fourth clear logic for handling loss of connection to ZATCA. When the Production Environment cannot be reached, your system must store the invoices in a durable queue and resend them when service returns, without losing any document and without breaking the hash chain. Designing this logic in advance is what distinguishes a passing outage from a compliance crisis.

All of the above means that managing Production is continuous engineering work: monitoring success rates, response time, the reporting queue, the certificate lifecycle, and outage logic. Building this layer and maintaining it in-house is a large effort that recurs with every regulatory update from ZATCA.

Production records and document retention

In Production, records gain legal value, not merely operational value. Keep a copy of every cleared invoice in its original signed XML form, along with the associated ZATCA response, its unique identifier, and its hash. This is not temporary data cleaned up after a few days; it is a tax record that must remain available for review and audit later.

Separate operational logs from document records. Operational logs help you trace errors and response time and may be cleaned periodically. The record of cleared documents, however, is a legal asset kept in full. Mixing the two is a common mistake that leads to losing a cleared document during a routine log cleanup, so the shortfall is discovered late when an audit is requested.

Observe as well the privacy of the data in these records. Production invoices carry real customer data, so keep them securely, restrict access to them, and do not leak them in exposed operational logs. This is part of the maturity of the Production layer, no less important than the correctness of the invoice itself.

Where does Qoyod fit in the Production Environment?

Qoyod is an e-invoicing solution compliant with Phase Two of e-invoicing. In practice this means Qoyod carries out on your behalf everything we explained in this guide about the Production Environment, without you writing a single line of integration, so you focus on your work instead of building and maintaining the Production layer.

Qoyod manages issuing the Production certificate (PCSID) for each device automatically, signs every live invoice with it, and generates the XML document in UBL 2.1 format with the QR code, the cryptographic stamp, and the connected hash chain. It also handles the instant Clearance path for business-to-business invoices, and the 24-hour Reporting path for consumer invoices, by the rules we detailed.

Qoyod also handles the layer many overlook: monitoring clearance rates, managing the certificate lifecycle and its renewal, and storing invoices in a durable queue on loss of connection and resending them when it returns. Qoyod also added validation of the format of tax identifiers at the moment of entry, catching one of the most common rejection causes before sending to ZATCA.

The role here is clear. The Fatoora platform is mandatory, and Qoyod is the launchpad to it, not an alternative. Qoyod handles the entire Production layer on your behalf with all its operational complexity, from the certificate to monitoring, so you get live cleared invoices without building an integration or maintaining it.