A Credit Note is a tax document issued by the seller to reduce the value of an invoice it had previously issued. When a customer returns goods, receives a discount after the sale, or an invoice is corrected for an overcharged amount, the original invoice may not be deleted or modified. The correct approach in the e-invoicing system is to issue a standalone credit note that references the original invoice and reduces its tax effect. This note is a complete document in its own right: it has its own number, its own unique identifier, and its own sequence, and it passes through clearance or reporting just like any invoice. This technical reference explains the credit note inside the XML file under Phase Two in Saudi Arabia, with ready-made snippets and a table for every value.
This guide is part of Qoyod’s technical documentation series for e-invoicing. Before continuing, it is best to be familiar with Invoice Structure and with Invoice Header, because the credit note is built on the same logic and differs from it in only a limited set of fields. Here we focus exclusively on what distinguishes the credit note: document type code 381, the reference field to the original invoice, the identifiers specific to each note, and how it passes through clearance or reporting.
An important note before the details: all values in the following snippets are illustrative examples. You do not write these fields manually in actual use; your accounting system generates them when the note is issued. The purpose of this reference is to help you understand what the system generates, so you can read the note with confidence and diagnose any rejection quickly. Qoyod’s e-invoicing software handles generating the note, linking it to the original invoice, and signing it automatically, so you never need to write XML yourself.
What is a credit note and when is it issued?
A credit note is a corrective document that reduces the amount due on a previous sale. It is issued by the seller in favor of the buyer, and is recorded in the books as a reduction of revenue and of the tax due. The core idea: the original invoice stays exactly as it is in the records, and the credit note sits on top of it to adjust its effect. This preserves the full audit trail, so the auditor sees the invoice and then the correction that was applied to it.
There are common cases that require issuing a credit note. The first is sales returns: the customer returns all or part of an item, so the value of the transaction is reduced by the amount returned. The second case is a subsequent discount on the sale, such as a settlement discount or a volume discount granted after the invoice was issued. The third case is correcting an error that led to an amount higher than the correct one, such as charging an inflated price or a quantity larger than what was delivered. In all these cases the direction is the same: reducing the value in favor of the buyer.
The credit note has a counterpart that moves in the opposite direction: the Debit Note. A debit note raises the value of a previous invoice instead of reducing it, and is used when charges are added, an understated amount is corrected, or price differences are computed in favor of the seller. The difference between the two is only in direction: the credit note reduces in favor of the buyer, and the debit note raises in favor of the seller. This reference is dedicated to the reduction side, that is, the credit note. The technical documentation of the debit note is a separate guide within the same series that explains type code 383 and the increase logic.
It is useful to distinguish between a credit note and cancelling an invoice. Cancellation is not available in the e-invoicing system once an invoice has been cleared, because a cleared document becomes part of a tax record that cannot be erased. What is available is correction via a credit or debit note. So if you want to nullify the effect of an entire invoice, you issue a credit note for its full value that references it, and its net effect equals zero without it disappearing from the record. This difference is fundamental: do not look for a “Delete invoice” button, but for “Issue a credit note.”
The same applies to partial and full credit notes. A partial note reduces part of the invoice value, such as when the customer returns one item out of several, so the note carries only the returned lines and their value. A full note reduces the entire invoice, so it carries all its lines at their original values. In both cases type code 381 stays constant, and the reference to the original invoice remains mandatory. What changes is the lines and amounts the note carries, not its structure.
Before we dive into the XML, the panel below summarizes when to choose each document, to serve as a quick reference when making the decision.
When do you issue a credit note versus a debit note?
| Criterion | Credit Note (381) | Debit Note (383) |
|---|---|---|
| Effect | Reduces the invoice value | Increases the invoice value |
| Cases | Returns or subsequent discounts | Additional charges or increases |
| Reference | References the original invoice | References the original invoice |
Document type code 381 in the credit note
The e-invoicing system distinguishes between document types through a single field named cbc:InvoiceTypeCode. This field carries a standard numeric code taken from the internationally adopted UN/CEFACT list. A standard tax invoice carries the code 388, while the credit note always carries the code 381. This code is what tells the Fatoora platform that the current document is a credit note and not a sales invoice, so it is treated within the system as a reduction and not as new revenue.
It does not stop at the code 381 alone. The same field carries an attribute named name that contains a string of seven digits describing the document subtype and its characteristics. The first digit of this string distinguishes between a standard tax invoice (B2B) and a simplified invoice (B2C): the value 01 means standard, and the value 02 means simplified. The remaining digits are flags that indicate characteristics such as the presence of exempt or zero-rated lines. The credit note inherits the type of the original invoice: a credit note on a B2B invoice stays standard, and a credit note on a simplified invoice stays simplified.
In this example, the value 381 specifies that the document is a credit note. The string 0211010 in the name attribute begins with 02, which means a simplified invoice (B2C), followed by the characteristic flags. Had the note been on a standard invoice, the string would begin with 01, becoming for example 0111010. The following table summarizes the most commonly used codes so they don’t get confused with one another.
| Document | Code InvoiceTypeCode |
Direction |
|---|---|---|
| Tax invoice | 388 | Revenue |
| Credit note | 381 | Reduces the value |
| Debit note | 383 | Raises the value |
The decisive rule here: a credit note is not rejected merely because it carries a corrective amount; it is rejected if it carries a wrong code or a name attribute that does not match the type of the original invoice. That is why the accounting system copies the type of the original invoice into the note verbatim.
Referencing the original invoice: BillingReference
The most distinctive thing about a credit note compared with an ordinary invoice is the requirement to reference the invoice it corrects. This reference is mandatory in every credit or debit note, and its absence is a direct cause of rejection. The reference is carried in a block named cac:BillingReference, and beneath it a sub-element named cac:InvoiceDocumentReference that carries the original invoice number in the cbc:ID.
field. The logic is simple: the credit note does not live alone. Its existence is tied to a previous invoice, and the system needs to know exactly which invoice this note reduces, so that the tax effect is computed accurately. If you issue a credit note with no reference, the system will not know which revenue you are reducing, and the file is rejected immediately at the validation stage.
The value inside cbc:ID here is the number of the original invoice as it appeared in the cbc:ID field of that invoice, not a new number. Any difference between this value and the actual number of the original invoice breaks the link. The following table shows the elements of the reference block and the position of each value.
| Element | Function | Mandatory in the credit note |
|---|---|---|
cac:BillingReference |
The block containing the invoice reference | Mandatory |
cac:InvoiceDocumentReference |
Grouping the reference document data | Mandatory |
cbc:ID (inside it) |
The original invoice number | Mandatory |
If the credit note corrects more than one invoice, the adopted practice is to issue a separate note for each original invoice, to preserve the clarity of the link and the audit trail. Linking one note to several invoices complicates validation and makes reconciliation harder later.
The reference block can also hold additional optional fields alongside the invoice number, most notably the unique invoice identifier UUID of the original invoice. Including this identifier strengthens the link, because it pinpoints the invoice precisely even if commercial numbers coincide across different periods. Some systems differ in relying on the commercial number alone or adding the unique identifier with it, and the safest is to include both whenever available, because that removes any ambiguity for the system in identifying the corrected invoice.
A practical point worth attention: a credit note may not reference an invoice that was never issued in the system, or a document that was cancelled before clearance, or another note instead of an invoice. The reference must be an actual, cleared sales invoice. This constraint protects the audit trail from convoluted reference chains that are hard to trace, and ensures that every reduction is based on revenue actually recorded.
How does the credit note link itself to the original invoice?
The original invoice
Credit note with BillingReference
The net effect after the reduction
The identifiers specific to each note: ID, UUID, ICV, and PIH
The credit note is a standalone document in the system, so it carries its full set of identifiers exactly like any invoice. It is not enough for it to reference the original invoice; it must itself have a commercial number, a globally unique identifier, a sequential counter, and a hash of the previous document. Understanding these identifiers helps you read the note and diagnose any flaw in the sequence.
The first field is cbc:ID, the commercial number of the note. It should have its own sequence within the establishment’s note numbering range, and it may not repeat a previous invoice number. The second field is cbc:UUID, a globally unique identifier the system generates for every document, so it never repeats between one note and another nor between a note and an invoice.
The next two identifiers live inside the signed UBL Extensions block, not in the visible header, but they are essential to the integrity of the sequence. The first is the invoice counter ICV , the Invoice Counter Value, a sequential number that increases with every document the establishment issues. The credit note takes the next counter value in the sequence, exactly as if it were a new invoice, because the system counts every signed document as one unit in the chain.
The second is the previous document hash PIH , the Previous Invoice Hash. Every signed document carries a hash of the document that immediately preceded it in the establishment’s sequence, forming a linked chain from which no link can be removed without detection. The credit note carries the hash of the document that preceded it in the sequence, whether an invoice or another note, and not necessarily the hash of the invoice it corrects. This is a point many confuse: the reference in BillingReference points to the corrected invoice, while PIH points to the last document signed in time. The following table details the difference.
| Identifier | What it points to | Source of the value |
|---|---|---|
cbc:UUID |
The identity of the note itself | Generated by the system for every document |
ICV |
The note’s order in the establishment’s sequence | The counter value after the last document |
PIH |
Hash of the chronologically previous document | The last document signed before this one |
BillingReference |
The original corrected invoice | The number of the invoice being corrected |
The practical takeaway: do not confuse the correction link with the sequence link. The first is logical and accounting-based, linking the note to its invoice, and the second is cryptographic, linking the note to the last document that preceded it. A certified accounting system handles both automatically, but knowing the difference makes you able to read any file and interpret any rejection.
Why does this distinction matter to you practically? Because most cases of confusion occur when diagnosing a rejection related to the sequence. When the system rejects a note because of PIH, some think the problem is in the original invoice, so they review its number in BillingReference to no avail. The truth is that the flaw is in the hash of the chronologically previous document, which is often a document unrelated to the corrected invoice. Understanding that the cryptographic sequence is completely independent of the correction logic points you to the right location of the error immediately, and shortens the resolution time.
The integrity of the sequence rests on a simple principle: every signed document locks onto the document that preceded it, forming a chain into whose middle no document can be inserted or removed without breaking the linkage. The credit note is no exception; it is a full link in this chain, taking its position in the counter and carrying the hash of its predecessor. This is what enables the system to detect any tampering with the chronological order of documents, and gives electronic books a reliability equal to that of a sealed paper ledger.
Amounts in the credit note: positive values in the opposite direction
A frequently recurring question: are the amounts of a credit note written with a negative sign? The answer is no. In the UBL standard adopted by the system, the amounts in a credit note remain positive values in their fields, such as cbc:LineExtensionAmount , the total tax, and the document total. The negative sign is not written inside the fields. What determines the direction is the document type code 381 itself, not the sign of the numbers.
In other words: the system reads the code 381 and understands that this document reduces, then subtracts its positive amounts from the seller’s tax effect. If you write the amounts as negative, validation breaks because the fields expect positive values. The rule, then: the amount is positive, and the direction is determined by the code. A credit note with a tax of 230 riyals means deducting 230 riyals from the output tax due, even though the number is written positively in the file.
In this example, the credit note reduces a value by 200 riyals before tax, and 30 riyals of value-added tax at 15%, making the total reduction 230 riyals. All values are positive, and the code 381 is what makes the system treat them as a reduction. Note also that the reason for the note is usually written in a document-level note field inside cbc:Note, such as “goods return” or “settlement discount,” so the audit trail stays clear.
How does the credit note pass through clearance or reporting?
Since the credit note is a complete tax document, it undergoes the same validation path as an invoice. And the path depends on the type of the original document. If the note is standard (B2B), it passes through Clearance: it is sent to the Fatoora platform before being handed to the buyer, the system validates it in real time and seals it, and then it becomes effective. But if it is simplified (B2C), it is Reported: it is handed to the buyer immediately, and sent to the system within 24 hours of issuance.
To understand the clearance mechanism in detail and how the system seals a standard document before it takes effect, see the guide Clearance in E-Invoicing. The principle governing the path choice for the credit note is that it inherits the path of the original invoice: a note on a standard invoice passes through clearance, and a note on a simplified invoice is reported. You do not choose the path manually; it is determined by the type of the invoice the note corrects.
The credit note’s path from issuance to effect
| Criterion | Standard B2B | Simplified B2C |
|---|---|---|
| The path | Clearance before delivery | Reporting within 24 hours |
| Timing | Immediate | After issuance |
| Subtype | 01 | 02 |
This distinction matters practically: a standard note does not become effective before the system seals it, so do not rely on a B2B note that has not yet been sealed. A simplified note, on the other hand, takes effect as soon as it is delivered, and reporting is a later step that does not hold up the process. The accounting system manages this difference automatically according to the type of the original invoice.
After clearance or reporting, the credit note carries the same elements as a cleared invoice: the system’s seal, and the response code (QR Code) that bundles the document data and the signature. This code lets the buyer and any authorized party verify the validity of the note without going back to the original system. And because the note reduces output tax, it matters to the buyer who deducted input tax on the original invoice to reflect this reduction in their return as well, so the two parties match before the system. This way the credit note preserves the consistency of the returns on both sides of the transaction, not the seller’s side alone.
Common errors that cause credit notes to be rejected
Most causes of credit note rejection are avoidable by understanding the fields we have explained. The first and most common error is the absence of BillingReference or its containing a non-existent invoice number. The second error is using a wrong code in InvoiceTypeCode, such as writing 388 instead of 381, so the document is treated as a revenue invoice and not a reduction. The third error is a mismatch of the name attribute with the type of the original invoice, such as issuing a standard note on a simplified invoice.
There are errors related to the sequence too. A non-sequential ICV value, or a PIH that does not actually match the hash of the previous document, break the linkage chain and lead to rejection. And there is the amounts error: writing them negative instead of positive. The following table gathers these errors and their solutions in one place.
| Error | Cause | Solution |
|---|---|---|
| Rejection for a missing reference | No BillingReference |
Add the correct original invoice number |
| Treated as revenue | Code 388 instead of 381 | Use 381 for the credit note |
| Type mismatch | name does not match the original |
Copy the type of the original invoice |
| Broken sequence | ICV or PIH wrong |
Let the system generate them automatically |
| Amounts rejection | Negative values in the fields | Write the values positive; the code determines the direction |
The overarching note: all these errors arise from manual intervention in the file. When a certified accounting system handles generating the note from a simple interface (you choose the original invoice, specify the return or discount, and it builds the rest), these errors disappear because the fields are filled directly from the original invoice data.
How does Qoyod help you issue credit notes?
In Qoyod, you do not deal with XML, nor with the code 381, nor with the reference block manually. You choose the original invoice from your invoice list, then specify what you want to reduce: a full return, specific lines, or a discount of a certain value. The system builds the credit note automatically with the correct type code, fills BillingReference with the number of the invoice you chose, and generates UUID andICV andPIH within your signed sequence.
After that the system handles the cryptographic signing of the note, then sends it for clearance if it is standard or reports it if it is simplified, according to the type of the original invoice. The accounting effect is reflected immediately in your books: the output tax due decreases by the amount of the note’s tax, and the value appears in the VAT return summary ready for review. All of this without touching a single line of XML.
Issue your credit notes with a single click
Qoyod builds the credit note from the original invoice, fills the reference and the identifiers, signs it, and sends it for clearance or reporting automatically under Phase Two in Saudi Arabia.
Where does the credit note fit within the rest of the technical documentation series?
The credit note is part of an interconnected system of documents. To understand the general shape of the invoice file and the arrangement of its major blocks, refer to Invoice Structure. To understand the header fields the note shares with the invoice, see Invoice Header. As for the certificate with which each document is signed, it is explained in the guide CSID Certificate, and the standard on which the fields are built in the guide The UBL 2.1 Standard.
. As for the opposite side of the credit note, it is the Debit Note, which raises the invoice value instead of reducing it with the code 383, and has its own separate guide within the same series. Remember the fundamental difference: the credit note reduces in favor of the buyer, and the debit note raises in favor of the seller, and both reference the original invoice and pass through clearance or reporting.
A reference summary for the credit note
The following table gathers the distinctive fields of the credit note in one place, to serve as a quick reference while reading a note or diagnosing a rejection.
| Field | Value in the credit note | Note |
|---|---|---|
cbc:InvoiceTypeCode |
381 | Specifies that it is a credit note |
attribute name |
Begins with 01 or 02 | Matches the type of the original invoice |
cac:BillingReference |
The original invoice number | Mandatory, and its absence is a rejection |
cbc:UUID |
A unique identifier for the note | Generated by the system |
ICV / PIH |
Sequence and hash | Within the signed chain |
| Amounts | Positive values | The code determines the direction of the deduction |
The credit note is simple in concept, precise in execution: it reduces the value of a previous invoice, references it clearly, and passes through the same validation path. And the good news is that you are not obligated to write any of these fields manually. A certified accounting system generates them per the standard in every note, and handles the signing and the linking with the Fatoora platform on your behalf, so your books stay consistent and your tax return accurate.
