BR-KSA-24 Warning — the invoice is accepted

Out-of-scope category without a reason code

A VAT breakdown whose category is O, outside the scope of VAT, carries a reason code too, and it has exactly one: VATEX-SA-OOS, with free text in which the taxpayer describes the case. It is a warning, so the invoice is accepted. The rule reads the document-level VAT breakdown, not the line.

The message text as the Authority sends it in English, unedited

A VAT breakdown (BG-23) with VAT Category code (BT-118) 'Not subject to VAT' shall have a VAT exception reason code (BT-121)

What does this mean?

The place being checked is the document's VAT breakdown (BG-23): every cac:TaxTotal/cac:TaxSubtotal/cac:TaxCategory whose cbc:ID (BT-118) is O. Inside it, cbc:TaxExemptionReasonCode (BT-121) must be present and must not be empty once spaces are trimmed. The check runs per breakdown, on tax invoices, simplified invoices and their notes alike.

The executable test in the compiled schematron the Authority ships with its SDK asks about presence only. The test text printed beside the message has something worth flagging: it spells the code backwards, VAT-OOS-SA. That text is not what runs, and the code the Authority accepts is VATEX-SA-OOS — so copying the code from the test text passes this rule and then fails BR-KSA-CL-04. That rule's message mentions only Z and E, but its executable condition has a branch for category O that accepts nothing but VATEX-SA-OOS.

This category has a single code, and the table in paragraph 11.2.4 of the XML implementation standard says its text is free, provided by the taxpayer case by case. The code is fixed and the text is a description: what made this line fall outside the scope. Wherever the code is present, the text must sit beside it in cbc:TaxExemptionReason (BT-120), or BR-KSA-83 warns, and it runs from 1 to 1,000 characters, or BR-KSA-F-06-C16 warns.

O is neither E nor Z: zero-rated is a taxable supply at 0%, exempt is a supply within scope that the law exempts, and this one is what falls outside the scope of VAT altogether. The difference between the letters is covered in BR-KSA-18, and the rate on such a line is zero under BR-KSA-11, which is an error. Which of your supplies are out of scope is a regulatory question the invoice does not settle.

It is a warning: the invoice is cleared or reported, and the code comes back with the acceptance in warningMessages. The European specification is satisfied here by a code or a text, through rule BR-O-10; the Authority's copy drops it and puts this rule in its place, so text alone is no longer enough. Prepayment lines have a twin of this rule, BR-KSA-95.

Why does it happen?

Ordered from the most common to the least — your cause is most likely the first or the second.

  • A system that treats O as no VAT, nothing to explain, and writes no code for a category where nothing is literally exempted.
  • The text Not subject to VAT in cbc:TaxExemptionReason with no code — which satisfies the European rule BR-O-10 and not this one.
  • The code copied backwards, VAT-OOS-SA, from the test text in the Authority's SDK: this rule passes and BR-KSA-CL-04 warns.
  • The reason written only on the line, in cac:Item/cac:ClassifiedTaxCategory, while the rule reads nothing except the document-level VAT breakdown.
  • The code element written empty or holding spaces when the template does not know the value, and to this rule empty is the same as absent.
  • The letter O chosen for a line whose treatment was never settled, because it looks lighter than an exemption. The missing code is then the least of the document's problems.

How to fix it

3 steps, then send the invoice again.

  1. 1
    Write VATEX-SA-OOS and a text describing the case

    Inside every cac:TaxSubtotal/cac:TaxCategory whose category is O, straight after cbc:Percent: <cbc:TaxExemptionReasonCode>VATEX-SA-OOS</cbc:TaxExemptionReasonCode>, then <cbc:TaxExemptionReason>…</cbc:TaxExemptionReason> with a text saying why the line falls outside the scope, then cac:TaxScheme. The code exactly as it is: VATEX first, then SA, then OOS.

  2. 2
    Keep the rate at zero in both places

    The VAT breakdown has category O and rate 0, and so does the line beside it in cac:ClassifiedTaxCategory: a non-zero rate on an out-of-scope line is an error that rejects the invoice under BR-KSA-11, which is more serious than this warning.

  3. 3
    Confirm that O is the right letter

    Before adding the code, ask whether the line really is out of scope, or exempt under one of the three exempt codes, or zero-rated. All three are 0% and all three sit differently in your return. The call belongs to your tax adviser and zatca.gov.sa, not to us, and not to a system that picks the letter because the VAT amount is zero.

This code does not block acceptance, so the invoice you have is compliant. Correct the data so the warnings disappear from future invoices.

Does ZATCA Tools prevent it?

Yes. Category O has a single code, so there is nothing to guess: every VAT breakdown with category O leaves ZATCA Tools with the code VATEX-SA-OOS and the text Outside scope of VAT: from the invoice form, from the API even when the line carries no tax_reason_code, and on a note that inherits its invoice's category. A code of another category on an O line is refused by the API before signing with invalid_lines. We have issued documents with out-of-scope lines on the Authority's sandbox and they were accepted without a warning. The Shopify integration never issues an out-of-scope line at all. One limit, stated plainly: our text is fixed, and there is no field where the merchant writes a description of the case as the standard allows.

Related codes

BR-KSA-CL-04 Warning
Exemption reason code (BT-121) not on the list for its category
BR-KSA-83 Warning
Exemption reason code without its reason text (BT-120)
BR-KSA-11 Rejects the invoice
Out-of-scope line carrying a non-zero rate
BR-KSA-69 Warning
Zero-rated category without an exemption reason code
BR-KSA-23 Warning
Exempt category without an exemption reason code
BR-KSA-18 Rejects the invoice
Tax category code not accepted

Frequently asked questions

Was my invoice rejected because of this code? +
No. It is a warning: the invoice is accepted and the warning is recorded with it. If it really was rejected, the cause is another code in the response, and the closest one to this situation is BR-KSA-11 if the rate on the line is not zero. How to read the response is covered in ZATCA error codes explained.
What text do I write with VATEX-SA-OOS? +
A text that describes the case as it is: the standard makes it free text provided by the taxpayer case by case. It runs from 1 to 1,000 characters. The schematron does not check its wording today, but it is part of the signed document and it is read at review.
I copied the code VAT-OOS-SA from the Authority's SDK and got BR-KSA-CL-04 — why? +
Because that order is what appears in the test text printed beside this rule, and it is not a code on the list. The right code is VATEX-SA-OOS, the only one the category O branch of BR-KSA-CL-04 accepts.
What is the difference between O and E when both are 0%? +
Exempt E is a supply within the scope of VAT that the law exempts, and it has three specific codes. O is what falls outside the scope altogether, with one code and free text. The four letters are covered in BR-KSA-18, and which one applies to your supply is a question for your adviser.
Does it apply to credit and debit notes? +
Yes. In this specification a note is a document with the same root element, and its VAT breakdown carries the same category, so an O breakdown on it needs its code just as on the invoice. The steps for notes are in credit and debit notes in Saudi e-invoicing.
You fixed this one — now avoid the next

ZATCA Tools builds the signature, the PIH, the counter and the encoding for you, and validates your data before it is sent. Start free, with no credit card.

Start for free

← All ZATCA error codes