BR-KSA-17Credit or debit note gives no reason for being issued
Mutabiq checks Saudi ZATCA Phase 2 e-invoice XML before you submit it: pre-validation against published ZATCA requirements, not an approval by the authority. This page explains one rule, BR-KSA-17.
Five checks a month on the Free plan. The file is checked in memory and is never stored.
The message ZATCA prints
[BR-KSA-17]-Debit and credit note (invoice type code (BT-3) is equal to 383 or 381) must contain the reason (KSA-10) for this invoice type issuing.
Also cited in this report
BR-KSA-17
[BR-KSA-17]-Debit and credit note (invoice type code (BT-3) is equal to 383 or 381) must contain the reason (KSA-10) for this invoice type issuing.
What Mutabiq reports
One entry for each way this rule can be reported.
Reported as
What kind of value was found — empty, not_15_digits and the like — never the value itself.
Credit or debit note gives no reason for being issued
Reported asinstruction_note_missingno reason for issue
What is wrong
The document is a credit note (381) or a debit note (383) and carries no cac:PaymentMeans/cbc:InstructionNote anywhere in it, so the reason for issuing (KSA-10) is absent. ZATCA makes that reason mandatory on both note types under BR-KSA-17 and refuses the document without it. The element is cbc:InstructionNote inside cac:PaymentMeans, and it is not cbc:Note. That distinction is the whole of the difficulty here: cbc:Note at document level is where a reader who knows UBL would put a reason, and where it looks entirely right, and it does not satisfy this rule - the check reads cac:PaymentMeans/cbc:InstructionNote and reads nothing else, so a note carrying a perfectly good explanation in cbc:Note is still refused. The check is presence only: it never looks at the text, so an empty cbc:InstructionNote satisfies ZATCA, and Mutabiq mirrors that and does not report a blank reason. The element may sit under any cac:PaymentMeans in the document, including one nested under a document-level allowance or charge.
What to check in your ERP
Credit and debit notes almost always carry a reason already - a return, a price correction, a cancellation, a rebate - as a reason code or a free-text field on the note header, so this is usually a mapping gap rather than missing data. Two causes account for most of it. The first is the element: check that the mapping writes cbc:InstructionNote and not cbc:Note. The second is the container: many exports emit cac:PaymentMeans only when a payment method is known, and a credit note often has none, so there is no block for the reason to sit in - the block has to be emitted for every note regardless. Write cbc:InstructionNote in its UBL position inside cac:PaymentMeans; an element written out of sequence fails the schema check instead and is reported as MTB-XSD-01.
The clause that runs
Quoted from the validation-rule stylesheet ZATCA publishes, at the file and line named below. The executed guard is what the check runs; the reported test is what it prints when it fails, and the two are not always the same.
As shipped in ZATCA SDK 3.4.8: the copy quoted here is, byte for byte, the file that release ships. The date in the file name is the name ZATCA gives the file; the rules in it are those of SDK 3.4.8.
A worked example
A synthetic document from the measured test corpus that trips this rule, shown where it differs from one that passed. Mutabiq's report names the class of the value, never the value itself.
Where it differs from a document that passed
− This example
+ A document that passed
<cac:PaymentMeans> <cbc:PaymentMeansCode>10</cbc:PaymentMeansCode>+A document that passed: <cbc:InstructionNote>Goods returned by the customer</cbc:InstructionNote></cac:PaymentMeans><cac:TaxTotal>