What each e-invoice status and alert colour means after the invoice is submitted to the Zakat, Tax and Customs Authority (ZATCA), why an invoice gets rejected, and how to correct it.
After e-invoicing is enabled, Qoyod sends issued invoices to ZATCA automatically. During that process different statuses and alerts may appear on the invoice, and each one carries a different meaning and a different action. Before doing anything, identify the invoice status and the alert colour shown on it first.
Path in Qoyod
Sales › Sales Invoices › View › Error message at the top of the invoice
Status “Sending” or “Processing”
It means the invoice was issued correctly inside Qoyod and was technically sent to the authority, but has not yet received an acceptance response or comments.
The invoice in this state is compliant and valid. The submission window depends on the invoice type: a simplified tax invoice is reported to the authority within 24 hours of being issued, while a standard tax invoice is cleared by the authority in real time before it is sent to the buyer.
It is not recommended to attempt to modify or reissue the invoice during this period.
Refresh the invoice page. If the status stays on “Processing” and does not change to “Successfully received” or “Received with alerts”, act as follows.
A standard tax invoice is cleared in real time, so there is nothing to wait for: start with the two steps below straight away. A simplified tax invoice has a 24-hour reporting window, so wait for it to pass and then take the same two steps:
- Check the connection status with the authority from: Settings, then Electronic Connection, then Connection with ZATCA. See Resolving ZATCA Integration Issues (Phase Two).
- If the connection is working normally, contact customer service to action this request, and have the invoice number and the business number ready.
Alert colours and their meanings
Green alert, “Successfully received”
- The invoice is fully accepted by the authority.
- There are no comments and no errors.
- No action is required.
Yellow alert, “Received with alerts”
- What it means: the invoice is accepted and compliant, there is no error, ZATCA takes no action on this invoice, and it does not affect the tax return.
- Why the alert appears: it is an advisory alert from the authority about future updates or upcoming new requirements.
- What to do: nothing. Just apply these notes to your future invoices. The invoice in this state is final and correct.
Red alert, “Rejected”
The invoice was not accepted by the authority, and there is an error that must be corrected.
- Open the invoice and click View.
- Read the error message shown at the top of the invoice.
- If you want more detail about the error, download the invoice in XML format from the bottom of the view page, then upload it to the ZATCA compliance portal.
- If the invoice is a standard tax invoice and not a simplified one, and the authority status is “invoice error”, the system creates a credit note automatically and links it to the invoice. No manual action is needed to create the credit note in this case.
- If the invoice is a simplified tax invoice, carry out these steps in order: issue a credit note to reverse the invoice, correct the cause of the error such as the date or the tax data, then reissue a new correct invoice.
A rejected invoice cannot be modified, and it cannot be resubmitted after correction. The solution is always a credit note followed by a new invoice.
Most common rejection reasons and their direct fixes
- Invoice date in the future: the authority rejects any invoice dated later than today. Fix: a credit note, then a new invoice dated today or earlier.
- Incorrect or missing VAT number: check that the VAT number in the business settings matches the authority’s record, and that it is 15 digits.
- Incompatible invoice type: check the invoice type, standard or simplified, against the buyer type, business or individual.
- Missing buyer information: on full standard invoices you must fill in the buyer name, address and VAT number. Check the customer data before issuing the new invoice.
- Tax calculation error: check that the applied tax rate is correct (15%) and that the totals are consistent.
If the rejection reason is not in the list above, look the code up in ZATCA Authority Alerts, or contact customer service to action this request and include the text of the error message shown when viewing the invoice.
Special cases
The “Resubmit to ZATCA” button
The resubmit button appears only on new invoices whose status is “Not applicable”. It is a recent feature in Qoyod.
It does not appear on old invoices issued before the feature was launched, on invoices that are still processing, or on rejected invoices.
If the button does not appear on an old invoice, contact customer service to action this request, and have the invoice number and the business number ready from: Settings, then Subscription Settings.
Checking the error detail accurately
From inside Qoyod: open the invoice, click View, and read the error or alert message at the top of the invoice.
Using the XML file: download the invoice in XML format, then upload it to the ZATCA compliance portal. This step is optional and diagnostic only. It helps clarify the error and does not replace correcting it inside the system.
Permissions for viewing invoice errors
Any user with permission to view invoices can see the alerts and errors, and can read the error message by viewing the invoice. There is no additional permission specific to e-invoicing errors.
The QR code does not appear on sales invoices
- E-invoicing is not enabled: go to Settings, then General Settings, enable “Electronic Invoicing in Compliance with Saudi Regulations”, then save. See How to Enable E-Invoicing (Phase One) and Display QR Codes on Invoices.
- The invoice is a draft: the QR code appears only on invoices with the “approved” status. Approve the invoice first.
- The custom template has no QR element: go to Settings, then Sales Invoice Settings, then the Tax Invoice Designer, add the QR Code element from Document Details, then save the template.
- It is a purchase invoice, not a sales invoice: according to the authority’s guidelines the QR code appears only on sales invoices and credit notes, not on purchase invoices and debit notes.
If you have tried every step and the QR code still does not appear, contact customer service to action this request. Have the business number and one specific invoice number where you saw the problem ready, and say whether the account is new or old and which invoice type it is, standard or simplified.
Quick summary
- Invoice processing: a simplified invoice has a 24-hour reporting window, while a standard tax invoice is cleared in real time. If the status does not change, contact customer service with the invoice number and the business number.
- Yellow alert: no action required, the invoice is correct.
- Red alert: credit note, then correction, then a new invoice.
- Resubmit button not visible: the invoice is old, so contact customer service.
- Understanding the error clearly: read the error message, or use the XML file for diagnosis.
- QR code not appearing: check that e-invoicing is enabled, that the invoice is approved, and that the QR element is in the template. If that does not help, contact customer service with the business number and the invoice number.
