Saudi Arabia (SA) Field Mapping
Country: SA
Compliance: ZATCA e-invoicing
Last Updated: 2026
This page includes the full Saudi Arabia field mapping and the Saudi country extension fields in one place.
| Parameter | Required | What It Means | Example |
|---|
| Document Type | Yes | The type of document being submitted (Invoice, Credit Note, or Debit Note). Determines the base document classification for KSA e-invoicing. | tax_invoice |
| Document ID | Yes | Unique identifier for the invoice within the seller's sequence. Must be unique per seller and follow KSA format. | INV-2024-001 |
| Issue Date | Yes | The date the invoice was created in YYYY-MM-DD format. Used for ZATCA tax period determination. | 2024-01-15 |
| Issue Time | Yes | The time the invoice was created in HH:MM:SS format. Used for precise timestamping with ZATCA. | 14:30:00 |
| Document Currency | Yes | ISO 4217 currency code. Defaults to SAR for KSA. Exchange rate required when currency differs from SAR. | SAR |
| Exchange Rate | Conditional | Currency conversion rate (required only when currency differs from SAR). | 3.75 |
| VAT Currency | No | Currency used for VAT calculations. Defaults to document currency. | SAR |
| Supply Start Date | Conditional | Required for period-based invoices. Start date of the supply period. | 2024-01-01 |
| Supply End Date | Conditional | End date of the supply period. Used for consolidated invoices. | 2024-01-31 |
| Billing Frequency | Conditional | Frequency of billing for consolidated invoices (monthly, quarterly, annually, weekly). | monthly |
| Due Date | No | Payment due date. Optional but recommended for cash flow management. | 2024-02-15 |
| Reference Invoice Number | Conditional | Reference to original invoice for credit/debit notes. Required for corrective documents. | INV-2023-999 |
| Note Issuance Reason | Conditional | Reason for issuing credit/debit note. Required for corrective documents. | Goods returned |
Seller Information Fields
| Parameter | Required | What It Means | Example |
|---|
| Seller Name | Yes | Legal registered name of the seller. Must match business registration with ZATCA. | Tech Solutions LLC |
| Seller ID | No | Internal ERP identifier for the seller. Optional but useful for system integration. | SEL-001 |
| VAT Number Type | Yes | VAT identification scheme for KSA (usually VAT or GVAT). | VAT |
| VAT Number Value | Yes | KSA VAT number in 15-digit format. Must be valid and registered with ZATCA. | 310075588700003 |
| Additional Seller ID Number | Yes | Commercial registration number (CRN). Required for business registration compliance. | 1234567890 |
| Additional Seller ID Type | Yes | Registration scheme type (CRN - Commercial Registration). | CRN |
| Seller Industry Classification | Yes | Industry classification code for business activity identification. | 61110 |
| Seller Contact Number | Yes | Seller contact phone number. Required for ZATCA communication. | +966501234567 |
| Seller Email | No | Contact email. Optional but useful for electronic communication. | info@techsolutions.sa |
| Address Line 1 | Yes | Primary street address. Must be complete and accurate for ZATCA verification. | King Fahd Road |
| Address Line 2 | No | Secondary address information. | Suite 100 |
| Building Number | Yes | Building number. Required in KSA for precise location identification. | 123 |
| District/Neighbourhood | Yes | District or neighbourhood. Required for local area identification. | Olaya |
| City | Yes | City name. Must match official city names for tax jurisdiction. | Riyadh |
| State | Yes | State name. Required for tax jurisdiction and regional compliance. | Riyadh Region |
| Postal Code | Yes | Postal/ZIP code. Required for address validation. | 11478 |
| Country | Yes | Country code. Must be 'SA' for KSA addresses. | SA |
| Seller Peppol ID | No | Peppol network identifier for cross-border e-invoicing. Optional for KSA. | 9930:SAxxxxxxxxxxxxxx |
Buyer Information Fields (B2B)
| Parameter | Required | What It Means | Example |
|---|
| Buyer Name | Conditional | Buyer name. Required for B2B transactions, optional for B2C. | ABC Corporation |
| Buyer ID | No | Internal identifier for the buyer. Optional for system integration. | BUYER-001 |
| Buyer VAT Number Type | Conditional | VAT identification scheme. Required for B2B transactions. | VAT |
| Buyer VAT Number Value | Conditional | Buyer VAT number in 15-digit format. Required for B2B transactions. | 301234567890001 |
| Buyer Additional ID Number | Conditional | Buyer registration number. Required for B2B transactions. | 9876543210 |
| Buyer Additional ID Type | Conditional | Buyer registration scheme type. Required for B2B transactions. | CRN |
| Buyer Peppol ID | No | Buyer Peppol identifier for cross-border transactions. Optional. | 9930:SAyyyyyyyyyyyyyyyy |
| Buyer Contact Number | Conditional | Buyer contact phone. Required for B2B transactions. | +966501111111 |
| Buyer Email | No | Buyer contact email. Optional but recommended. | info@abccorp.sa |
| Buyer Address Line 1 | Conditional | Buyer primary address. Required for B2B transactions. | Prince Road |
| Buyer Address Line 2 | No | Buyer secondary address. | Floor 5 |
| Buyer Building Number | No | Buyer building number. Optional. | 456 |
| Buyer District | No | Buyer district. Optional. | Downtown |
| Buyer City | Conditional | Buyer city. Required for B2B transactions. | Jeddah |
| Buyer State | Conditional | Buyer state. Required for B2B transactions. | Makkah Region |
| Buyer Postal Code | Conditional | Buyer postal code. Required for B2B transactions. | 21461 |
| Buyer Country | Conditional | Buyer country code. | SA |
Line Items Fields
| Parameter | Required | What It Means | Example |
|---|
| Line Item ID | Yes | Unique identifier for each line item. Used for referencing items in the invoice. | LINE-001 |
| Item Description | Yes | Detailed description of the product or service. Supports multi-language. | Professional consulting services |
| Item Name | No | Short item name for product identification. Optional. | Consultation |
| Unit Price | Yes | Price per unit. Must be accurate for VAT calculations. | 1000.00 |
| Line Item Qty | Yes | Quantity of items ordered. Used for total calculations. | 5 |
| Units of Measurement | No | Unit code (PCE for pieces, HUR for hours, SET for sets). | HUR |
| Line Item Discount | No | Discount amount for this line. Applied before VAT. | 100.00 |
| Discount Rate | No | Discount percentage. | 10 |
| Discount Reason Code | No | Code explaining the discount. | 95 |
| Charge Amount | No | Any additional charges for this line. | 50.00 |
| Charge Reason Code | No | Code explaining the charge. | AA |
| Line Item Taxable Amount | Yes | Total line amount before VAT. Calculated as (Qty × Price) - Discounts. | 4900.00 |
| VAT Category Code | Yes | VAT category (S=Standard 15%, Z=Zero, E=Exempt, O=Out of scope). | S |
| VAT Rate On Line Item | Yes | VAT rate percentage. | 15 |
| Line Item VAT Amount | Yes | VAT amount for this line. Calculated as Taxable Amount × Rate. | 735.00 |
| Line Item Sub Total | Yes | Total including VAT. Calculated as Taxable Amount + VAT. | 5635.00 |
| Item Classification Code | Conditional | Product classification code. Required for goods. | 39301 |
| Item Classification Name | No | Description of the classification. Optional. | Consulting Services |
| VAT Exemption Reason Code | Conditional | Exemption code (required if VAT Category = Exempt). | VATEX-SA-32 |
| VAT Exemption Reason Text | Conditional | Text explaining the exemption. | Export of services |
Totals and Amounts Fields
| Parameter | Required | What It Means | Example |
|---|
| Summation of Line Taxable Values | Yes | Sum of all line item taxable amounts. Used for VAT verification. | 14700.00 |
| Total Taxable Amount Excluding VAT | Yes | Total invoice amount before VAT. | 14700.00 |
| VAT Total | Yes | Total VAT amount for entire invoice. Sum of line VAT amounts. | 2205.00 |
| Invoice Total Amount | Yes | Final amount payable including VAT. | 16905.00 |
| Discount at document level | Conditional | Document-level discount. Applied after line-level calculations. | 500.00 |
| Amount Due for Payment | Yes | Final amount due. Calculated as total - prepaid amounts. | 16405.00 |
| Pre-Paid Amount | No | Amount already paid in advance. | 0.00 |
| Rounding Amount | No | Rounding adjustment amount. Must be within acceptable limits. | 0.05 |
Payment Information Fields
| Parameter | Required | What It Means | Example |
|---|
| Payment Means | Yes | Payment method code (CASH, CREDIT, PAYMENT_TO_BANK_ACCOUNT, BANK_CARD, INSTRUMENT_NOT_DEFINED). | PAYMENT_TO_BANK_ACCOUNT |
| Payee Bank Account Number | Conditional | Supplier's IBAN for payment. Required for bank transfers. Format: SA + 22 digits. | SA1234567890123456789012 |
| Payment Terms description | No | Free-text description of payment terms. | Payment due within 30 days |
| Prepayment Reference Number | No | Reference number for prepayments. Optional. | PREP-2024-001 |
KSA Digital Fields
| Parameter | Required | What It Means | Example |
|---|
| Invoice Counter Value | Yes | Sequential counter for ZATCA digital signature. Required for compliance. | 1 |
| Previous Invoice Hash | Yes | Hash of previous invoice for chain verification. Required for ZATCA. | NWZlY2E3YzcxNzQ... |
| QR Code | Yes | Base64 encoded QR data. Required for ZATCA compliance. | A0A0A0A0A0A0A0... |
| Digital Signature | Yes | Digital signature data for authenticity. Required for ZATCA. | MEUCIQD... |
| Prepayment ID | Conditional | Unique identifier for prepayments. | PREP-001 |
| Prepayment Issue Date & Time | Conditional | Date when prepayment issued. | 2024-01-10 |
| Prepayment Issue Time | Conditional | Time when prepayment issued. | 10:00:00 |
| Prepayment Document Type Code | Conditional | Document type for prepayment (always '386' for KSA). | 386 |
| Prepayment VAT Category Code | Conditional | VAT category for prepayment. Must match final invoice. | S |
| Prepayment VAT Rate | Conditional | VAT rate for prepayment. Must match final invoice. | 15 |
| Prepayment Taxable Amount | Conditional | Taxable amount of prepayment. | 1000.00 |
| Prepayment Tax Amount | Conditional | VAT amount of prepayment. | 150.00 |
| Prepayment Adjustment Amount | Conditional | Adjustment amount for prepayment. | 0.00 |
Country Extensions
Saudi Arabia currently applies:
sa_prepayment fields in tax_invoice, credit_note, debit_note
| Field path | Label | Description | Data type | Req | Applies to |
|---|
extensions.sa_prepayment.paymentId | Prepayment Payment ID | Prepayment ID. | string | CM | tax_invoice, credit_note, debit_note |
extensions.sa_prepayment.issueDate | Prepayment Issue Date & Time | Prepayment date. | date | CM | tax_invoice, credit_note, debit_note |
extensions.sa_prepayment.documentType | Prepayment Document Type Code | Always 386 for prepayments. | string | CM | tax_invoice, credit_note, debit_note |
extensions.sa_prepayment.vatCategory | Prepayment VAT Category Code | Tax category. | string | CM | tax_invoice, credit_note, debit_note |
extensions.sa_prepayment.vatRate | Prepayment VAT Rate | Tax rate percentage. | number | CM | tax_invoice, credit_note, debit_note |
extensions.sa_prepayment.taxableAmount | Prepayment Taxable Amount | Amount subject to tax. | number | CM | tax_invoice, credit_note, debit_note |
extensions.sa_prepayment.taxAmount | Prepayment Tax Amount | VAT amount. | number | CM | tax_invoice, credit_note, debit_note |
extensions.sa_prepayment.adjustmentAmount | Prepayment Adjustment Amount | Adjustment amount. | number | CM | tax_invoice, credit_note, debit_note |
See Also
