Credit note

By Matheel, from ZATCA's specifications and SDK 3.4.8 · Updated

A ZATCA credit note (code 381) refunds the buyer or corrects an invoice. It must reference the original invoice and state the reason for issuing it.

A credit note is issued by the seller to refund the buyer or to correct an invoice issued with an error. Its type follows the original invoice: a note against a standard invoice is standard (01), against a simplified invoice it is simplified (02). An invoice already filed with ZATCA cannot be edited; corrections go through notes.

In the XML it is code 381 in cbc:InvoiceTypeCode, and it needs two things: the original invoice number in cac:BillingReference/cac:InvoiceDocumentReference/cbc:ID, and the reason in cac:PaymentMeans/cbc:InstructionNote. It is a document in the device chain and takes an ICV and PIH like any invoice.

What goes wrong: no reason fails BR-KSA-17, an error that rejects. No reference to the original fails BR-KSA-56. The most common mistake is sending negative amounts because the shop platform records a refund as negative, which breaks BR-KSA-F-04. Amounts on a note are always positive; code 381 carries the direction.

On Matheel you send "document_type": "credit_note" with original_invoice_number and note. Matheel turns negative amounts positive and, if no reason is given, adds a fixed refund reason so the note is not rejected.

Example

<cac:BillingReference>
    <cac:InvoiceDocumentReference>
        <cbc:ID>INV-1001</cbc:ID>
    </cac:InvoiceDocumentReference>
</cac:BillingReference>
...
<cac:PaymentMeans>
    <cbc:PaymentMeansCode>10</cbc:PaymentMeansCode>
    <cbc:InstructionNote>عند ترجيع السلع أو الخدمات | In case of goods or services refund</cbc:InstructionNote>
</cac:PaymentMeans>

FAQ

Can I edit an invoice that was already filed?

No. Issue a credit note against it, then a new invoice if needed.

Are credit note amounts negative?

No. All amounts are positive and code 381 marks it as a credit note. A negative amount breaks BR-KSA-F-04.

Related ZATCA rules

Related terms

Let Matheel handle this for you

Matheel signs the invoice, files it with ZATCA and keeps the counter and hash in one request, and returns the PDF with the QR.

Try Matheel, no signup Matheel API docs