Error Code 1020: Original Invoice Reference Missing in the Note

If you issue a credit or debit note against an earlier invoice and the Fatoora platform returns error code 1020, the meaning is direct: the note carries no reference to the original invoice it is amending. This error never appears on standard invoices, only on notes (credit and debit), because a note is by nature a document that depends on an invoice that preceded it, and has no meaning in isolation from it. This page explains the error at its root: why a note must carry the original invoice reference, exactly where that reference goes inside the XML file, how to read the rejection message, how to fix the note and resubmit it, and how to prevent it from recurring for good.

This guide is part of the ZATCA invoicing error code reference, within the Qoyod e-invoicing system. The target audience is the developer, integration analyst, or accountant who runs the technical issuance and wants a precise understanding of the cause, not just a surface step. Technical English codes such as BillingReference are kept as is because they are actual field names in the standard.

What error code 1020 means exactly

Error code 1020 is a rejection at the note structure validation level. The platform inspects the document before clearing it, and if it is a credit or debit note and it does not find the reference block that ties it to the original invoice, it stops the note and rejects it with a message indicating that the original invoice reference is missing.

The important thing to understand is that the rejection here is not arbitrary. The validation rule is explicit: every credit or debit note must carry a BillingReference block that defines the number of the original invoice it amends. A missing block, an empty one, or one placed in the wrong position all produce code 1020.

A credit note (Credit Note) carries the type code 381, and a debit note (Debit Note) carries the code 383. Both are documents that amend an existing invoice, so they are subject to the same rule: there must be a reference pointing to the original. A standard invoice is not subject to this rule because it is a self-contained document that amends nothing before it.

How to read the rejection message

When the note is rejected, the platform returns a response carrying the document status and a list of validation errors. Each error carries a code, a category, and a message. The following block is an illustrative example of a rejection response caused by a missing original invoice reference in a credit note. Copy it and compare it against the response structure your system returns.

{
  "validationResults": {
    "infoMessages": [
      {
        "type": "INFO",
        "code": "XSD_ZATCA_VALID",
        "category": "XSD validation",
        "message": "Complied with UBL 2.1 standards"
      }
    ],
    "warningMessages": [],
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "1020",
        "category": "Billing reference validation",
        "message": "Original invoice reference is missing for a credit/debit note."
      }
    ],
    "status": "ERROR"
  },
  "clearanceStatus": "NOT_CLEARED",
  "clearedInvoice": null
}

The keys that matter to you when reading it:

• clearanceStatus with the value NOT_CLEARED means clearance did not happen, so the note was not approved and must not be handed to the buyer.
• status inside the validation results with the value ERROR means the reason for the stop is a blocking error, not just a warning.
• code with the value 1020 is the precise definition of the cause, and the message explains it in text.
• clearedInvoice with the value null confirms that there is no stamped copy returned to you.

The practical rule: do not look at the text message alone, but read the code because it is fixed and does not change, whereas the wording of the message may differ slightly between versions. The category category here points to the billing reference, so it directs you straight to the location of the fault.

Why a note must carry the original invoice reference

The answer starts from the function of the note itself. A credit or debit note is not a standalone document, but an amendment to an invoice that was issued before it and was actually approved. A credit note lowers the value of an earlier invoice (a return, a later discount, an over-charge correction), and a debit note raises its value (a price difference, a forgotten line, an under-charge correction). In both cases, the amendment has no meaning unless it is known exactly which invoice is being amended.

In other words: the original invoice reference is the link that proves this note amends a real document that exists in the Authority’s records, not an amount suspended in a vacuum. Without this reference, the platform cannot tie the note to the original, and cannot track the tax effect of the amendment on the VAT collected earlier. That is why the rule rejects the note from the outset.

Compare this to a standard invoice. An invoice is a primary document that creates a new tax obligation, so no document precedes it for it to amend, and it requires no reference to any invoice. This is the essence of the difference: the reference requirement is tied to the nature of the note as a dependent document, not to its form.

This has an important consequence in design: if your system issues invoices and notes together, it must not apply the same rule to both. The BillingReference block is a conditional field: mandatory when the type code is 381 or 383, and absent in a standard invoice. Treating it as a fixed field on all of them produces either error 1020 on the note, or a needless block on the invoice. To understand the full technical structure of notes, see the guides Credit Notes technically andDebit Notes technically.

Where the original invoice reference goes in the XML file

The original invoice reference has one specific position in the note, and any placement of it outside this position equals its absence from the validation’s point of view. The position is the cac:BillingReference block, and specifically inside cac:InvoiceDocumentReference in the element cbc:ID that carries the original invoice number. The following block shows the correct structure:

<cbc:InvoiceTypeCode name="0211010">381</cbc:InvoiceTypeCode>

<cac:BillingReference>
  <cac:InvoiceDocumentReference>
    <!-- Number of the original invoice the note amends -->
    <cbc:ID>INV-2026-000148</cbc:ID>
  </cac:InvoiceDocumentReference>
</cac:BillingReference>

Three precise points in this block:

1. The reference goes in cbc:ID inside cac:InvoiceDocumentReference inside cac:BillingReference, not in any other position. A common mistake is to put the number in a notes or description field, so the validation rule does not read it as an invoice reference.
2. The value in cbc:ID must match the original invoice number as it was actually issued (the cbc:ID field in that invoice), not the note number itself, nor any other internal number.
3. The type code InvoiceTypeCode must be 381 for a credit note or 383 for a debit note. If the type code is 388 (invoice), then the document is not a note at all, and the fault is in the classification, not in the reference.

And for a direct comparison, this is what the note that produces error 1020 looks like: a document with a note type code, but with no BillingReference block at all.

<cbc:InvoiceTypeCode name="0211010">381</cbc:InvoiceTypeCode>

<!-- BillingReference block completely missing -> produces error 1020 -->

<cac:AccountingSupplierParty>
  ...
</cac:AccountingSupplierParty>

Notice that the rest of the note may be completely sound: the lines are correct, the totals are balanced, and the stamp is in place. The absence of a single block that ties the note to its original is enough to stop the whole document. To understand the rest of the note’s elements and their position in the tree, see the guide Credit Notes technically.

The difference between an invoice and a note in the reference field

The following table summarizes when the original invoice reference is mandatory, and what results from its absence in each document type:

How to fix the note and resubmit it

Fixing error 1020 does not require changing the whole structure of the note, only completing a single block. Follow these steps in order:

1. Confirm the document type first. Open the type code element and verify that it is 381 or 383. If it is 388 , then the document is an invoice and should not require a reference at all, and the fault is in the document classification, not in the reference field.
2. Get the correct original invoice number. Extract the number of the invoice the note amends from your records. Verify that it matches the cbc:ID field in that invoice as it was actually issued, not a different internal number.
3. Add the BillingReference block in the correct position. Place the original invoice number in cbc:ID inside InvoiceDocumentReference, as in the correct sample above.
4. Verify that both parties on the note match the original invoice. The note inherits the seller and buyer data from the invoice it amends. If the buyer or their tax number differs from the original, neighboring validation errors may surface after 1020 is resolved.
5. Regenerate the document and sign it again. Any change in the note’s content changes its hash, so do not settle for adding the block; regenerate the file and stamp it with the CSID certificate before sending.
6. Resubmit to clearance. Pass the corrected note through local validation first, then send it. On successful clearance you will get a clearanceStatus with the value CLEARED and a stamped copy in clearedInvoice.

An important note about resubmission: do not resend the rejected note as is, thinking the problem is transient. A 1020 rejection is a fixed structural rejection, and it will recur until you actually complete the reference block. Also, do not create a new note with a new sequential number to bypass the rejected one, because the document counter ICV must remain sequential. Fix the note itself and regenerate it with the same counter.

The step-by-step path to fixing error 1020

This path works as a quick checklist every time code 1020 appears. The two most-overlooked steps are regenerating after the change, and making sure the entered number is the original invoice number, not the note number, so do not skip them.

Common mistake: pointing to the wrong or unapproved document

Adding the reference block alone is not always enough. Sometimes the block is present but its value is wrong, so the error shifts from a missing reference to a reference that does not match an approved invoice. Watch out for these cases:

• Pointing to the note number itself. A recurring mistake is for the system to fill cbc:ID with the note number instead of the original invoice number. The reference must point to the original, not to the current document.
• Pointing to an invoice that has not yet been approved. The original invoice must have actually passed through clearance. Pointing to a draft or a rejected invoice does not tie the note to a document that exists in the Authority’s records.
• A difference in how the number is written. The number in the reference must match the invoice number literally as it was issued. A difference in the prefix, the zeros, or the separators makes the platform unable to match the reference to the original.
• Pointing to an invoice of a different party. The note amends an invoice addressed to the same buyer. A reference to another customer’s invoice breaks the consistency of the two parties between the two documents.

Automatically validating that the number entered in the reference actually exists in the record of approved invoices catches most of these errors before they reach the platform. And when the note is issued directly from the original invoice screen, the reference is filled with its number automatically, so these errors do not happen at all.

A practical scenario: a goods return that needs a credit note

Let us take a real case that explains when the error appears and why. A food distribution company sold a shipment to a restaurant on an approved standard invoice. A few days later the restaurant returned part of the shipment due to damage, so the company needed to issue a credit note lowering the invoice value by the amount of the return. The accountant opens a new note screen, sets the discount value and the returned lines, and issues the note, which comes back rejected with code 1020.

The reason for the rejection here is that the accountant created the note as a standalone document without tying it to the original invoice of the shipment. The system built the note with the lines and the value, but the BillingReference block came out missing, so the validation rule stopped the note. Notice that the accountant did not make a mistake in the value or the lines; the fault was in an earlier step, which is tying the note to its invoice.

The solution in this case is practical and direct: the accountant opens the original invoice of the shipment, issues the credit note from it directly instead of creating it from scratch, so the reference is filled with the invoice number automatically, then regenerates the note so the reference block is built in full, and clearance passes successfully. The lesson learned: error 1020 usually reveals that the note was issued in isolation from its original. An establishment that always issues its notes from the original invoice screen will never face this scenario.

How to verify the reference is correct before issuance

Before approving any note, verify these points so you do not move from error 1020 to another reference error:

• The type code is correct. 381 for credit and383 for debit. An incorrect code changes the validation rule applied entirely.
• The reference points to the original. The value in cbc:ID is the original invoice number, not the note number nor another internal number.
• The original invoice is approved. The invoice referenced has actually passed through clearance, so the note is not amending a draft.
• The two parties are consistent. The note’s seller and buyer match the original invoice. Any difference breaks the relationship between the two documents.

How to prevent the error from recurring for good

Error 1020 is one of the most preventable errors, because its cause is a wrong issuance procedure, not a deep technical fault. The following measures close the door on it:

• Always issue the note from the original invoice. Instead of creating the note as a standalone document, open the invoice to be amended and issue the note from it. This way the reference is filled automatically with its correct number.
• Make the reference block mandatory in any document of type 381 or 383. Do not allow saving a note without a valid invoice reference, so the document does not reach the sending stage with an empty reference block.
• Validate locally that the reference matches an approved invoice. Add a check that rejects the note if the reference number does not match any invoice that passed through clearance, so you catch the error in your system instead of the platform catching it.
• Separate the notes flow from the invoices flow. Design your system so that any note starts from selecting an existing invoice, not from a blank screen, so it becomes impossible to issue it without an original.
• Use an invoicing system that builds the reference block automatically. When the system ties the note to its invoice directly, the human error that produces 1020 disappears.

These measures together turn error 1020 from a recurring problem into a rare case that appears only on an incomplete manual issuance, and is then caught locally before it reaches the platform.

What happens if you leave the error unresolved

Error 1020 is not an alert you can bypass, but a rejection that stops the note legally. As long as clearanceStatus with the value NOT_CLEARED, the note is not approved and must not be handed to the buyer. In practice this means the amendment to the original invoice has not yet been recorded, no matter how complete the note looks in your system.

The effect extends to both parties. You cannot amend the previously recorded revenue with an approved note, and the buyer cannot adjust the input tax they deducted from the original invoice. A delayed correction keeps the original invoice at its old value in both parties’ records, and holds up the settlement of the account between you. That is why dealing with 1020 the moment it appears is cheaper than deferring it.

A final important point: the same rule applies to every note, whether credit or debit, and to standard and simplified invoices alike. As long as the type code is 381 or 383, the reference block is mandatory without exception. Treat the note with the same care you treat the original invoice.

The effect of the correction on the hash chain and the document counter

Many developers fix error 1020 by adding the reference block, then are surprised by a new error related to the hash or the counter. The reason is that adding the block is not an innocent change to the text, but a change in the document’s content that requires rebuilding its related elements. Understanding this interdependence saves you a second round of rejection.

The hash value (hash) is computed from the document’s entire content. As long as you added the BillingReference block, the content has changed, and therefore the expected hash has changed. Resending the note with its old hash after changing its content produces a mismatch. So regenerate the document in full to recompute its hash on the new content before signing.

Likewise, pay attention to the document counter ICV and the previous document hash value PIH. The rejected note did not enter the approved chain, so it does not consume a place in it. On resubmission, the corrected note must carry the same counter and the same previous hash value it would have carried, not jump to a new number. Jumping breaks the sequence of the chain and produces a different error. Fix the content while preserving the document’s position in the sequence.

The practical takeaway: the correction is three interconnected moves, not a single one. Add the reference block, regenerate the document so the hash is computed anew, then sign it and send it while preserving the counter. Skipping any of these moves shifts the problem from one code to another.

Notes in the clearance path vs. the reporting path

You need to understand where the reference validation sits in the note’s journey, because the path differs depending on the type of the original invoice. The note inherits the path of the invoice it amends: a note on a standard invoice (B2B) goes through instant clearance, and a note on a simplified invoice (B2C) is reported within 24 hours.

In the clearance path, the validation of the reference block happens in real time before the note is approved. You send the document, the platform inspects it, and if the reference is missing, code 1020 comes back to you immediately before any approval. The advantage here is that you know about the problem before handing the note to the other party, so you do not hand over an invalid document.

In the reporting path, the simplified note is issued and handed over first, then reported to the platform within 24 hours. Here code 1020 may reach you in the reporting response after the note has already been handed over, so you are forced to issue a corrected note and report it anew. For this reason, local validation that the reference block is complete before issuance is preferable in both paths, so you do not discover the shortfall late in the reporting path. The details of the difference between the two paths are in the ZATCA invoicing error reference.

The position of the original invoice reference within the note tree

This tree sums up the whole rule: the original invoice number goes in cbc:ID inside InvoiceDocumentReference inside BillingReference, not in any other field. Placing it out of position equals its absence. To fully understand the structure of notes technically, see Credit Notes technically andDebit Notes technically, and to review the rest of the error codes see ZATCA invoicing error reference.

Frequently asked questions

What is the difference between a credit and a debit note in their relationship to error 1020?
Both are subject to the same rule. The credit note (type code 381) lowers the value of an earlier invoice, and the debit note (383) raises it, and both are amending documents that require the original invoice reference in the BillingReference block. A missing reference in either produces error 1020.

Does error 1020 appear on a standard invoice?
No. A standard invoice (type code 388) is a primary document that amends nothing before it, so it requires no reference at all. If 1020 appears to you on a document you think is an invoice, then it was most likely classified as a note (381 or 383) by mistake in the type code.

Where exactly does the original invoice reference go in the file?
inside cac:BillingReference / cac:InvoiceDocumentReference / cbc:ID, and the value is the original invoice number as it was issued. Putting the number in a notes or description field is not read by the validation as an invoice reference and produces the same error.

Is the reference the note number or the original invoice number?
The original invoice number that the note amends, not the note number itself. A common mistake is for the system to fill the reference with the note number, so the error persists because the reference does not match an approved invoice.

Do I resend the rejected note as is after adding the reference?
No. Any change in the content changes the note’s hash, so you must regenerate the document and sign it with the CSID certificate again before resubmitting to clearance. Add the block, regenerate, then send.

How do I prevent error 1020 from recurring in the future?
Issue every note directly from the original invoice screen, make the reference block mandatory in any document of type 381 or 383, and add a local check that rejects the note if the reference does not match an approved invoice. Qoyod builds this block automatically from the invoice, so the error never reaches you in the first place.