How to handle credit notes in KSA e-invoicing



How Do You Issue a Compliant Credit Note Under ZATCA Phase 2 Rules?

Direct Answer: A compliant ZATCA credit note is a UBL 2.1 document assigned InvoiceTypeCode “381” that must be cryptographically linked — via a BillingReference chain and a Previous Invoice Hash (PIH) — to a previously cleared (B2B) or reported (B2C) original tax invoice on the Fatoora platform. It must be issued within 15 calendar days from the end of the month in which the supply adjustment occurred, and it must carry a valid KSA-10 InstructionNote reason code matching one of the five legally recognized adjustment triggers defined in the ZATCA data dictionary. Failure to satisfy any one of these structural, temporal, or cryptographic requirements produces an immediate rejection at the Fatoora API gateway, rendering the document legally void.

This guide walks through every dimension of ZATCA-compliant credit note architecture, from regulatory obligations to byte-level XML mappings. Specifically, you will learn:

• The legal framework under Article 40 of the KSA VAT Implementing Regulations and the five permitted reason codes for issuing a credit note under ZATCA’s data dictionary.
• The structural and cryptographic differences between Standard (B2B) credit notes processed under the Clearance Model and Simplified (B2C) credit notes submitted under the Reporting Model.
• The exact UBL 2.1 XML tags, data types, and nested block structures required to pass ZATCA Phase 2 validation, including InvoiceTypeCode, BillingReference, UUID chaining, and TaxTotal aggregation.
• The top five validation errors and their associated ZATCA error codes that cause rejections in both the Fatoora sandbox and production environments.
• Practical optimization rules and architectural best practices for ERP and EGS developers building ZATCA-compliant credit note workflows.

ZATCA Legal Compliance & The 5 Valid Reason Codes

The Regulatory Foundation: Article 40 of the KSA VAT Implementing Regulations

The legal authority governing the issuance of credit and debit notes in the Kingdom of Saudi Arabia originates in Article 40 of the Value Added Tax Implementing Regulations, promulgated by the Zakat, Tax and Customs Authority (ZATCA). This article establishes that any taxable supplier who has issued a tax invoice and subsequently needs to adjust the taxable value or the VAT amount of that supply — for any legally recognized reason — is obligated to issue a tax adjustment document that formally amends the original invoice and modifies the associated VAT liability on both the supplier’s and the buyer’s VAT records.

Under ZATCA’s framework, a credit note functions as a negative adjustment document: it reduces the taxable value of the original supply and, correspondingly, reduces the VAT amount that was previously charged and reported. A debit note, by contrast, increases the taxable value. Both document types share a common structural skeleton in the UBL 2.1 schema but are differentiated by their InvoiceTypeCode values — “381” for credit notes and “383” for debit notes — with the name attribute providing additional processing flags in a six-digit binary string.

The Mandatory 15-Day Issuance Timeline

One of the most operationally critical compliance constraints under Article 40 is the issuance deadline. The regulation does not grant an open-ended window for adjustment: the credit or debit note must be generated and submitted to the Fatoora platform within 15 calendar days from the end of the calendar month in which the supply adjustment event occurred.

The 5 Legally Recognized Adjustment Triggers

ZATCA’s data dictionary and the broader VAT regulatory framework define exactly five categories of events that legally justify the issuance of a credit or debit note. Attempting to issue a credit note for any reason outside these five categories is non-compliant.

• Total or Partial Cancellation or Suspension of the Original Commercial Supply This covers scenarios in which a contract or commercial agreement is cancelled — either in its entirety or partially — after a tax invoice has already been issued. If a supplier ships goods and the buyer subsequently exercises a contractual right to cancel the order before delivery is complete, the portion of the supply that is cancelled must be reversed using a credit note that reduces both the taxable value and the VAT amount to reflect the actual supply that took place. The InstructionNote within the XML must explicitly describe this cancellation.
• Material Changes or Amendments in the Supply Nature Leading to a Revised VAT Calculation When the nature of the supply changes materially after the original invoice is issued — for instance, a service initially classified under one VAT rate or exemption category is subsequently reclassified — the VAT calculation on the original invoice becomes incorrect. A credit note is required to reverse the incorrect VAT charge, and a corrected new invoice may then be issued with the updated classification. This scenario requires careful documentation of the nature change within the InstructionNote.
• Pre-Agreed Amendments to the Financial Value of the Supply Commercial negotiations frequently result in post-invoice adjustments to the agreed price of a supply. Volume discounts, early-payment rebates, retroactive price amendments negotiated between contracting parties, or loyalty-based pricing adjustments applied after the original invoice date all fall into this category. Each such adjustment must be captured in a credit note that precisely quantifies the financial delta being reversed.
• Material Return of Goods or Rejection of Services When a buyer physically returns goods to the supplier, or formally rejects a delivered service on verifiable grounds, the supplier must reverse the supply value and the corresponding VAT through a credit note. This is perhaps the most operationally frequent trigger in B2B commerce. The credit note amount must correspond exactly to the taxable value of the returned or rejected goods or services, and the Instruction Note must clearly identify the nature and scope of the return or rejection.
• Rectification of Clerical Errors or Accidental Overcharges on the Original Tax Invoice If the original tax invoice contained a factual or computational error — such as an incorrect quantity, wrong unit price, miscalculated discount, or transcription error — a credit note is required to correct the financial impact of that error. This trigger is particularly sensitive from a compliance perspective, because a correction credit note creates an audit trail that directly exposes the error in the original document. Both the original invoice and the corrective credit note must be retained and cross-referenced in the supplier’s VAT records.

Deep-Dive Architecture & UBL 2.1 XML Structure

Overview: Standard vs. Simplified Credit Notes

ZATCA Phase 2 mandates two structurally distinct credit note models, each corresponding to a different VAT invoice type and submission pathway:

Standard Credit Notes (B2B — Clearance Model): These are issued against original Standard Tax Invoices, which are themselves subject to real-time clearance by ZATCA before they are legally valid. A Standard Credit Note must therefore reference a cleared original invoice. The document is submitted to the Fatoora clearance API, where ZATCA validates the cryptographic chain, the billing reference, and all structural fields in real time before returning a cryptographic clearance stamp. Only after receiving a CLEARED status from the API is the credit note legally effective.

Simplified Credit Notes (B2C — Reporting Model): These are issued against original Simplified Tax Invoices. The EGS generates the Simplified Credit Note locally, signs it using a device-bound ECDSA key, embeds a QR code containing six mandatory TLV-encoded fields, and reports it to the Fatoora reporting API within 24 hours of issuance. Real-time clearance is not required, but the cryptographic chain, the digital signature, and the QR code contents must all be structurally valid and complete.

<cbc:InvoiceTypeCode name="381">

The InvoiceTypeCode element is the foundational identifier that signals to the Fatoora platform that the submitted document is a credit note rather than a tax invoice. The element carries two values simultaneously: a numeric code of “381” as the element’s text content, and a name attribute that encodes additional behavioral processing flags using a 6-digit binary string aligned to the KSA document type code table.

For a Standard (B2B) Credit Note under the Clearance Model, the name attribute value is "381000", where the first three digits encode the document subtype and the subsequent three digits encode processing flags. For a Simplified (B2C) Credit Note under the Reporting Model, the name attribute value is "381100", where the “1” in the fourth position signals the simplified invoice flag. Mismatches between the name attribute value and the actual document structure will cause an immediate schema validation failure at the Fatoora API gateway.

<cac:BillingReference> Block

The BillingReference block is architecturally the most critical element in the entire credit note structure, because it establishes the mandatory 1-to-1 linkage between the credit note and its original tax invoice. ZATCA requires this reference to be unambiguous, structurally complete, and to correspond to an invoice that already exists in the Fatoora system with a CLEARED or REPORTED status.

The block nests two child elements that function in concert. The <cbc:ID> element must contain the exact sequential invoice number of the original tax invoice — character for character, including any prefix conventions or zero-padding used in the supplier’s ERP system. This is not a fuzzy-matched or approximate field: the value must correspond precisely to the InvoiceID that was submitted and cleared or reported in the original invoice transaction. Any deviation — including trailing spaces, inconsistent capitalisation, or a mismatched numbering prefix — will trigger a BR-KSA-56 validation error.

<cbc:UUID> Mapping for Audit Chain Consistency

The <cbc:UUID> element nested within BillingReference must contain the 128-bit Universally Unique Identifier of the original tax invoice, formatted as a standard 8-4-4-4-12 hexadecimal string. This UUID is generated by the EGS at the time the original invoice is first created and must be stored persistently in the EGS or ERP system’s database so that it can be reliably retrieved at credit note generation time.

Failure to include the UUID, or including an incorrect UUID that does not match the original invoice’s UUID in the ZATCA ledger, breaks the cryptographic audit chain and will trigger a validation failure during the clearance or reporting API call. UUID values must be treated as immutable identifiers: they must never be regenerated, reformatted, or truncated.

KSA-10 Field: <cbc:InstructionNote> Reason Code

The KSA-10 field — implemented in XML as <cbc:InstructionNote> nested within the <cac:PaymentMeans> aggregate — is the mandatory natural-language reason code that must accompany every credit and debit note. This field is not optional and cannot be left empty, null, or populated with a generic placeholder. The text value must describe the reason for the adjustment in a manner that maps substantively to one of the five legally recognized triggers defined in Section 2.

The PaymentMeansCode value of “10” is the ZATCA-mandated code for credit/debit note payment means within the KSA extension namespace. While ZATCA does not mandate a specific controlled vocabulary for the InstructionNote text, the content must be substantively meaningful and clearly identify the legal trigger category. A value like “Adjustment” without further qualifying context will pass schema validation but may be flagged during a ZATCA manual audit or tax inspection.

<cac:TaxTotal> and Cryptographic Hash Chaining

The TaxTotal block in a credit note follows the same structural rules as in a standard tax invoice but uses negative monetary values that represent the tax being reversed. The TaxableAmount must be mathematically consistent with the sum of all LineExtensionAmount values across every InvoiceLine element in the credit note, and the TaxAmount must equal the TaxableAmount multiplied by the applicable VAT percentage, rounded to two decimal places using standard half-up rounding applied at the subtotal level — not accumulated from pre-rounded line amounts. Deviations of even SAR 0.01 due to incorrect rounding methodology will trigger a tax subtotal mismatch validation error.

Cryptographic Hash Chaining (PIH — Previous Invoice Hash): For both Standard and Simplified credit notes, ZATCA requires the document to include a reference to the SHA-256 hash of the immediately preceding document in the EGS’s sequential invoice chain. This is stored in the <cac:AdditionalDocumentReference> block with a document ID of “PIH”. The EmbeddedDocumentBinaryObject value is the Base64-encoded SHA-256 hash of the canonicalized XML of the immediately preceding document in the EGS’s sequential chain — not necessarily the original invoice being referenced by the BillingReference. This distinction is a frequent source of architectural confusion and implementation errors.

The Top 5 Common Validation Mistakes & ZATCA Error Codes

• Error 1: Missing or Invalid Original Invoice Reference (BR-KSA-56 Violation)

ZATCA business rule BR-KSA-56 mandates that every credit note contain a valid BillingReference pointing to the exact InvoiceID and UUID of an existing, cleared, or reported original invoice associated with the submitting supplier’s VAT registration number. This error manifests in two variants: the BillingReference block is absent from the XML document, or the <cbc:ID> value inside <cac:InvoiceDocumentReference> does not match any invoice in the ZATCA system. Both variants trigger an immediate API rejection with an error payload explicitly identifying BR-KSA-56. Remediation requires retrieving the exact invoice number from the EGS’s persistent storage and reconstructing the BillingReference block with exact character-level fidelity.

• Error 2: Tax Subtotal Mismatches and Rounding Discrepancies

The <cac:TaxSubtotal> element enforces strict mathematical consistency between TaxableAmount, TaxAmount, and the sum of InvoiceLine extension amounts. A frequent implementation error arises when developers compute VAT at the individual line level and then sum pre-rounded line-level VAT amounts to produce the TaxSubtotal TaxAmount. This approach accumulates rounding errors across lines. ZATCA requires that the TaxableAmount at the subtotal level be computed as the exact arithmetic sum of all line-level taxable amounts without intermediate rounding, and the TaxAmount at the subtotal level be computed by multiplying that total TaxableAmount by the applicable rate — with rounding applied only once, at that final step.

• Error 3: Mismatched or Incomplete QR Codes for Simplified Credit Notes

Simplified Credit Notes must embed a QR code that encodes exactly six data fields in Base64 TLV (Tag-Length-Value) format: the Seller Name, the Seller VAT Registration Number, the Timestamp of issuance (ISO 8601 format), the Invoice Total including VAT, the Total VAT Amount, and the SHA-256 hash of the signed XML document. A common implementation error is generating the QR code before the XML document is fully signed and finalized, which renders the embedded XML hash incorrect, or omitting one of the six mandatory TLV fields. ZATCA’s reporting API validates the QR code contents against the submitted XML, and any mismatch causes the reporting request to fail with a structured error response.

• Error 4: Invalid Cryptographic Hash Chain (PIH Mismatch)

The Previous Invoice Hash (PIH) stored in the AdditionalDocumentReference block must be the SHA-256 hash of the canonicalized XML of the immediately preceding document in the EGS’s sequential chain. A common error occurs when ERP developers reset or reinitialize the hash chain following a system failure or database restoration, causing the PIH in the next submitted document to reference a hash that ZATCA’s ledger does not recognize or expect. This breaks the cryptographic ledger chain for that EGS unit. Remediation typically requires engaging ZATCA through a formal compliance channel to request a chain reset procedure, which involves re-provisioning the EGS device credentials.

• Error 5: Clearance Sequence Violation for B2B Credit Notes

A Standard Credit Note (B2B) can only legally reference an original Standard Tax Invoice that has already achieved a “CLEARED” status on the Fatoora platform. Attempting to submit a credit note against an invoice that is in a PENDING, FAILED, or REJECTED state — or that was never submitted to ZATCA — constitutes a Clearance Sequence Violation. The Fatoora API returns an error indicating that the referenced invoice does not exist in a cleared state. ERP integration workflows must implement a status-check mechanism that verifies the clearance status of the original invoice before initiating credit note generation and submission. A credit note workflow without this pre-flight check is architecturally incomplete.

Also Read: Common Electronic Invoicing Errors and How to Avoid Them in Saudi Arabia

How Wafeq Handles ZATCA-Compliant Credit Notes

For businesses operating in Saudi Arabia, managing the technical complexity of ZATCA Phase 2 credit notes manually is neither practical nor scalable. This is where Wafeq provides direct, built-in support.

Wafeq is a ZATCA-certified cloud accounting solution that automates every structural and cryptographic requirement covered in this guide. When you issue a credit note inside Wafeq, the system automatically assigns the correct InvoiceTypeCode of 381, retrieves the original invoice's sequential ID and UUID to build a valid BillingReference, computes tax totals at the subtotal level using the correct single-pass rounding methodology, generates the PIH from the preceding document in your EGS chain, and submits the document to the Fatoora clearance or reporting API, depending on the transaction type.

For B2C simplified credit notes, Wafeq's embedded EGS solution generates the ECDSA signature locally using your provisioned CSID and encodes all six mandatory TLV fields into the QR code before the document is finalized. For B2B standard credit notes, Wafeq performs a pre-submission clearance status check on the original invoice before allowing the credit note to be generated — eliminating the clearance sequence violation error at the workflow level.

In short, Wafeq removes the engineering burden of ZATCA compliance from your team and ensures that every credit note your business issues is structurally correct, cryptographically valid, and legally effective from the moment it is created.

Read Also: Why is the Fatoora Portal Rejecting Your Invoices? Practical Solutions for ZATCA Integration Errors

FAQs about how to handle credit notes in KSA e-invoicing

Is it legal to issue a single credit note against multiple ZATCA tax invoices?

No. ZATCA’s regulatory framework and its UBL 2.1 implementation mandate a strict 1-to-1 relationship between a credit note and the original tax invoice it adjusts. This constraint is not merely a technical convention — it is architecturally enforced through the BillingReference block, which accommodates exactly one InvoiceDocumentReference element pointing to exactly one original invoice’s sequential ID and UUID. The reason for this strict linkage is the preservation of the cryptographic audit trail: each credit note must be traceable to a single, unambiguous, cleared, or reported document. If a supplier needs to issue adjustments against three separate invoices, three separate credit notes must be independently generated and submitted to the Fatoora platform. Bundling multiple invoice adjustments into a single credit note document will fail the BR-KSA-56 business rule validation.

What happens if a credit note fails ZATCA API validation during real-time clearance?

When a Standard (B2B) Credit Note fails ZATCA’s real-time clearance API validation, the Fatoora platform returns an HTTP 400 or HTTP 422 response containing a structured error payload that identifies the specific business rules violated and the XML paths responsible for the failure. The credit note is not cleared, and it cannot be legally issued to the buyer or recorded in the supplier’s VAT accounts. The ERP or billing system must parse the error payload, identify the root cause of each validation failure, and generate a new corrected XML instance — not a patched version of the failed document. The new instance must carry the same invoice number but must include an updated signing timestamp and a recalculated ECDSA cryptographic signature. The PIH in the resubmission must reflect the hash of the last successfully cleared or reported document in the EGS’s chain — not the failed submission, which is not recorded in the ZATCA ledger.

Are simplified credit notes (B2C) required to have an embedded cryptographic signature?

Yes. Simplified Credit Notes issued in the B2C Reporting Model are required to carry an ECDSA (Elliptic Curve Digital Signature Algorithm) cryptographic signature generated locally by the EGS device. Unlike Standard Credit Notes, which receive a cryptographic clearance stamp from ZATCA’s servers during real-time clearance, Simplified Credit Notes are self-signed by the EGS using a device-bound cryptographic certificate provisioned through ZATCA’s onboarding process — specifically the CSID (Cryptographic Stamp Identifier) issued during the compliance phase API handshake. The digital signature is embedded in the XML within the <ds:SignatureValue> element inside the UBL extension block. Additionally, the QR code printed or displayed on the Simplified Credit Note must include the SHA-256 hash of the signed XML as one of its six mandatory TLV fields, ensuring that the printed document and the reported XML are cryptographically bound and tamper-evident. An EGS that issues Simplified Credit Notes without a valid ECDSA signature is in direct violation of ZATCA’s Phase 2 technical standards.

How does an SME differentiate between a credit note and a debit note inside the XML schema?

The differentiation between a credit note and a debit note in ZATCA’s UBL 2.1 schema is achieved entirely through the <cbc:InvoiceTypeCode> element. A credit note — which reduces the taxable value of an original supply and decreases the supplier’s VAT liability — must use the code value “381”. A debit note — which increases the taxable value of an original supply and increases the supplier’s VAT liability — must use the code value “383”. The name attribute of the InvoiceTypeCode element changes correspondingly: "381000" or "381100" for Standard and Simplified credit notes respectively, and "383000" or "383100" for Standard and Simplified debit notes respectively. Both document types share identical BillingReference structures, UUID chaining requirements, KSA-10 InstructionNote obligations, and PIH-based cryptographic chaining. The InvoiceTypeCode value is the sole binary switch that determines whether the document is processed as a downward or upward financial adjustment in ZATCA’s audit ledger.