Mapping fields into an invoice payload, or checking one a supplier sent you? Here is the list itself, block by block, with the validation rule behind each field.
First, the distinction that decides how you triage a response. Of the 135 rules we index from ZATCA's SDK schematron, 44 reject an invoice and 91 come back alongside acceptance. An error means the document does not exist as far as the Authority is concerned; a warning means it was accepted with the defect recorded.
Two documents, one field list with a hole in it
A standard tax invoice (B2B, B2G) is cleared by the Authority before the buyer receives it. A simplified tax invoice (B2C) is handed over immediately and reported within 24 hours. Phase 1 has been mandatory since 4 December 2021; Phase 2 arrives in waves, wave 25 (VAT-taxable revenue above 187,500 SAR in any of 2022 to 2025) integrating from 1 February 2027.
Nearly every field below is common to both; the difference is the buyer block, and it is not cosmetic — a VAT-registered buyer cannot deduct input VAT from a simplified invoice. Standard vs simplified settles which you owe.
Seller fields
| Field | What it must carry | Rule and severity |
|---|---|---|
| Seller name (BT-27) | Registered name | Required by the specification |
| VAT registration number (BT-31) | 15 digits, first and last digit 3 | BR-KSA-39 missing, error; BR-KSA-40 malformed, error |
| Street name (BT-35) | From the national address | BR-KSA-09, warning |
| Building number (KSA-17) | Not inside the street text | |
| District (KSA-3) | Most often missing | |
| City (BT-37) | As registered | |
| Postal code (BT-38) | 5 digits (BR-KSA-66, warning) | |
| Country code (BT-40) | SA, ISO two-letter | |
| Other seller ID (BT-29), scheme (BT-29-1) | Commercial registration or similar | BR-KSA-08, warning; BR-KSA-F-13, warning |
Six elements are required, but a missing one produces BR-KSA-09 — a warning, returned alongside acceptance: the invoice clears and the gap is recorded against you. Take all six from the national address, not the commercial registration, which carries neither the district nor the building number.
Buyer fields
| Field | When it is required | Rule and severity |
|---|---|---|
| Buyer name (BT-44) | Standard invoice and its notes | BR-KSA-42, warning |
| Buyer VAT number (BT-48) | Standard invoice, registered buyer | BR-KSA-44 malformed, error; BR-CUSTOM-VALIDATION-01 same as the seller's, error |
| Other buyer ID (BT-46), scheme (BT-46-1) | Buyer not VAT-registered | BR-KSA-14, error; BR-KSA-81, warning |
| Street (BT-50), city (BT-52), country (BT-55) | Standard invoice; not simplified | BR-KSA-10, warning |
| Building number (KSA-18), district (KSA-4), postal code (BT-53) | Buyer country code is SA | BR-KSA-63, warning; BR-KSA-67 not 5 digits, warning |
What decides this block is the buyer's registration, not their size or the amount. A registered buyer is identified by the VAT number; a buyer without one is identified by another kind of identification, sent with the scheme identifier that says which document it came from. BR-KSA-14 names the accepted schemes, and it rejects.
Now the honest part: the regulation requires the buyer VAT number on a standard invoice, but no rule in the schematron rejects an invoice for its absence — BR-KSA-44 rejects only a number present and malformed, and BR-KSA-81 is a warning when neither identifier is there. Clearance is not proof that your buyer block is complete.
Document-level fields
| Field | What it must carry | Rule and severity |
|---|---|---|
| Invoice type code (BT-3) | 388 invoice, 381 credit note, 383 debit note | BR-KSA-05, error |
| Transaction code (KSA-2) | NNPNESB; 01 standard, 02 simplified | BR-KSA-06, error |
| Invoice number (BT-1) | The number a human reads | Required by the specification |
| UUID (KSA-1) | Letters, digits, dashes; one per document | BR-KSA-03, error |
| Issue date (BT-2) | Not in the future | BR-KSA-04, error |
| Issue time (KSA-25) | hh:mm:ss, or hh:mm:ssZ for UTC | BR-KSA-70, error |
| Currency (BT-5), tax currency (BT-6) | ISO 4217; tax currency must be present | BR-KSA-68, error; BR-KSA-CL-01, error |
| Invoice counter, ICV (KSA-16) | Digits only, incrementing, never reset | BR-KSA-33 missing, error; BR-KSA-34 non-numeric, error |
| Previous invoice hash, PIH (KSA-13) | Base64 SHA-256 of the previous document | BR-KSA-61, warning; BR-KSA-26, warning |
Two are confused constantly. The UUID is a machine identifier, not the invoice number a human reads, and it may not carry a slash. The ICV is a counter, not the invoice number either: digits only, so INV-001 and 2026/14 both reject. Date and time are two fields — storing only a date passes every date rule and fails BR-KSA-70.
Line-level fields
| Field | What it must carry | Rule and severity |
|---|---|---|
| Item name (BT-153) | What was supplied | Required by the specification |
| Quantity (BT-129), unit price (BT-146) | Positive values | BR-KSA-F-04, error |
| Line net amount (BT-131) | Quantity times price, plus charges, less allowances | BR-KSA-EN16931-11, warning |
| VAT category code (BT-151) | One of S, Z, E, O | BR-KSA-18, error |
| VAT rate (BT-152) | 0 where the category is O | BR-KSA-11, error |
| Line VAT (KSA-11), line total with VAT (KSA-12) | Standard invoice and its notes | BR-KSA-52, BR-KSA-53, errors |
The category is a letter, the rate is a number: S standard-rated, Z zero-rated, E exempt, O outside the scope. The list is closed at four — AE, a lower-case s or the figure 15 each reject.
Totals and the QR code
The totals block carries the total without VAT, the VAT amount, the total with VAT and the amount due, and the arithmetic between them is checked. Amounts and quantities must be positive (BR-KSA-F-04, error); where a tax currency code is present, one tax total without subtotals is expected (BR-KSA-EN16931-09, warning).
The Phase 2 QR code is a Base64 string of TLV fields — tag, length, value — eight of them:
| Tag | Field | Phase |
|---|---|---|
| 1 | Seller name | Phase 1 and Phase 2 |
| 2 | Seller VAT registration number | |
| 3 | Timestamp of the invoice | |
| 4 | Invoice total with VAT | |
| 5 | VAT total | |
| 6 | Hash of the XML invoice | Phase 2 only |
| 7 | ECDSA signature | |
| 8 | Public key of the stamp |
If the last three are absent, a Phase 1 system produced it. Scan any invoice with the free QR code reader: it decodes in your browser and lists the fields actually present.
What people most often get wrong
In rough order of cost: the invoice number written into the ICV or the UUID, which are neither of them the invoice number; a date with no issue time; a seller address copied off the commercial registration, so the district and building number stay empty; a half-typed buyer VAT number on a simplified invoice; notes issued without a reason (BR-KSA-17, error) or without a reference to the original invoice — mandatory by the rule, a warning from the validator (BR-KSA-56).
Two surface later: keeping only the PDF, when the document is retained six years in the format issued — the signed XML; and treating clearance as an audit, when VAT is due at the earlier of supply, invoice or payment.
Where the authoritative list lives
This page is a working reference, not the regulation. The authoritative and current list is ZATCA's own at zatca.gov.sa, and it is versioned: these rules come from one SDK release's schematron, and a later release can change a message, a severity or a field. More important, a field being present is not the same as it being correct: a validator can confirm your postal code is five digits, not that it is your postal code. Our error code reference covers the codes themselves, and how to read a rejection covers what to do when one arrives.
If you want these fields filled for you: ZATCA Tools connects to Fatoora in minutes with one OTP, signs every invoice with a compliant QR code, clears standard invoices and reports simplified ones, and archives the signed XML for six years. Rejections arrive with the official code and a link to its guide (135 codes documented, 24 with full written guides). It also issues quotations, credit and debit notes, receipt vouchers, per-customer statements, and branch devices with their own chain. Integrations: WooCommerce, Shopify, n8n, WHMCS, a REST API and a Partner API. It is not an accounting system. Free during the launch period, starting at 50 invoices and expanding — start here.