Saudi Arabia (SA) Field Mapping
Country: SA
Compliance: ZATCA e-invoicing
Last Updated: 2026
Requirement Legend
M: MandatoryCM: Conditional Mandatory (required only when condition applies)O: Optional
Field Mapping Reference
1) Core Invoice Information
| User Field Name | GETS Field | Mandatory/Optional/Conditional | KSA Rule | Sample Values |
|---|
| Document ID | header.documentId | M | Must be unique within seller sequence | 01HZY6KQ2YJ8X2V7QK4F3B9Z7A |
| Document Type | header.documentType | M | Hierarchical { base, variant?, modifiers? } | { "base": "tax_invoice" } |
| Issue Date | header.issueDate | M | Format YYYY-MM-DD | 2024-01-15 |
| Issue Time | header.issueTime | M | Format HH:MM:SSZ | 10:30:00Z |
| Supply Start Date | header.invoicePeriod.startDate | CM | Required for period-based invoices | 2024-01-01 |
| Supply End Date | header.invoicePeriod.endDate | O | Period end date | 2024-01-31 |
| Reference Invoice Number | header.referenceId | CM | For credit/debit notes | INV-2023-999 |
| Currency | header.currency | M | ISO 4217 code | SAR |
| Exchange Rate | header.exchangeRate.rate | CM | Required if currency is not SAR | 3.75 |
| Source Currency Code | header.exchangeRate.sourceCurrency | O | Exchange source currency | USD |
| Target Currency Code | header.exchangeRate.targetCurrency | O | Exchange target currency | SAR |
| Exchange Date | header.exchangeRate.date | O | Exchange rate date | 2024-03-20 |
| VAT Currency | header.taxCurrency | M | Tax reporting currency | SAR |
| Note Issuance Reason | header.noteIssuanceReason | CM | For credit/debit notes | Goods returned |
2) Seller Details
| User Field Name | GETS Field | Mandatory/Optional/Conditional | KSA Rule | Sample Values |
|---|
| Seller ID | parties.seller.partyId | O | Internal ERP identifier | KSA-SELLER-001 |
| Seller Name | parties.seller.name | M | Legal registered name | Al Riyadh Trading Co. |
| VAT Number | parties.seller.taxIds[type="VAT"].value | M | KSA VAT format (15 digits) | 310075588700003 |
| Group VAT Number | parties.seller.taxIds[type="VAT_GROUP"].value | CM | Group VAT registration | 300000000000003 |
| Additional Seller ID Type | parties.seller.registrationNumbers[].type | O | Registration type (for example CRN) | CRN |
| Additional Seller ID Number | parties.seller.registrationNumbers[].value | CM | Commercial registration | 1010123456 |
| Address Line 1 | parties.seller.address.addressLine1 | M | Street name | King Fahd Road |
| Address Line 2 | parties.seller.address.addressLine2 | M | Additional address info | Building 12A |
| Building Number | parties.seller.address.additionalAddressData.buildingNumber | M | KSA-specific requirement | 1234 |
| Additional Number | parties.seller.address.additionalAddressData.extensions.sa_additionalNumber | O | Additional reference number | 1234 |
| District/Neighbourhood | parties.seller.address.additionalAddressData.district | M | District name | Al Olaya |
| City | parties.seller.address.city | M | City name | Riyadh |
| State | parties.seller.address.stateOrProvince | M | Province/region | Riyadh Province |
| Zip Code | parties.seller.address.postalCode | M | Postal code | 11564 |
| Country | parties.seller.address.country | M | ISO 3166-1 alpha-2 | SA |
3) Buyer Details
| User Field Name | GETS Field | Mandatory/Optional/Conditional | KSA Rule | Sample Values |
|---|
| Buyer ID | parties.buyer.partyId | O | Internal identifier | KSA-BUYER-001 |
| Buyer Name | parties.buyer.name | CM | Required for B2B/B2G | Jeddah Supermarket |
| VAT Number | parties.buyer.taxIds[type="VAT"].value | CM | Required for B2B/B2G | 311122334455663 |
| Group VAT Number | parties.buyer.taxIds[type="VAT_GROUP"].value | CM | Group VAT registration | 300000000000003 |
| Additional Buyer ID Type | parties.buyer.registrationNumbers[].type | CM | Registration type | CRN |
| Additional Buyer ID Number | parties.buyer.registrationNumbers[].value | CM | Commercial registration | 2010123456 |
| Address Line 1 | parties.buyer.address.addressLine1 | CM | Required for B2B/B2G | Corniche Road |
| Address Line 2 | parties.buyer.address.addressLine2 | CM | Additional address | Building 34B |
| Building Number | parties.buyer.address.additionalAddressData.buildingNumber | O | Building reference | 34B |
| Additional Number | parties.buyer.address.additionalAddressData.extensions.sa_additionalNumber | O | Additional reference | Al Hamra District |
| District/Neighbourhood | parties.buyer.address.additionalAddressData.district | O | District name | Al Hamra |
| City | parties.buyer.address.city | CM | Required for B2B/B2G | Jeddah |
| State | parties.buyer.address.stateOrProvince | O | Province/region | Makkah Province |
| Zip Code | parties.buyer.address.postalCode | CM | Required for B2B/B2G | 23212 |
| Country | parties.buyer.address.country | CM | ISO 3166-1 alpha-2 | SA |
4) Payment & Prepayment Details
| User Field Name | GETS Field | Mandatory/Optional/Conditional | KSA Rule | Sample Values |
|---|
| Payment Means | payment.paymentMeans[].paymentMeansCode | O | UNCL 4461 code | 30 |
| Payment Terms | payment.paymentTerms[].note | CM | Required when payment terms apply | Net 30 days |
| Payee Account Number | payment.paymentMeans[].creditTransferInfo.payeeFinancialAccountId | CM | Bank account number | SA4420000001234567891234 |
| Prepayment ID | extensions.sa_prepaymentId | CM | Prepayment identifier | PP-2024-001 |
| Prepayment Issue Date & Time | extensions.sa_prepaymentDate | CM | Prepayment timestamp | 2024-01-15T14:30:00Z |
| Prepayment Document Type Code | extensions.sa_prepaymentTypeCode | CM | Always 386 for prepayments | 386 |
| Prepayment VAT Category Code | extensions.sa_prepaymentTaxCategory | CM | VAT category | S |
| Prepayment VAT Rate | extensions.sa_prepaymentTaxRate | CM | VAT rate | 15.0 |
| Prepayment Taxable Amount | extensions.sa_prepaymentTaxableAmount | CM | Taxable amount | 1000.00 |
| Prepayment Tax Amount | extensions.sa_prepaymentTaxAmount | CM | VAT amount | 150.00 |
| Prepayment Adjustment Amount | extensions.sa_prepaymentAdjustmentAmount | CM | Adjustment amount | 50.00 |
5) Line Item Details
| User Field Name | GETS Field | Mandatory/Optional/Conditional | KSA Rule | Sample Values |
|---|
| Line Item ID | lineItems[].id | M | Unique line identifier | 1 |
| Line Item Type | lineItems[].lineType | O | normal or prepayment | normal |
| Item Name | lineItems[].name | M | Product/service name | Office Supplies |
| Item Description | lineItems[].description | M | Product/service description | Consulting Service |
| Unit Price | lineItems[].price.amount | M | Price per unit | 500.00 |
| Item Price Discount | lineItems[].discountsOrCharges[isCharge=false].amount | M | Unit discount amount | 50.00 |
| Net Unit Price | lineItems[].netPrice | M | Price after discount | 450.00 |
| Line Item Qty | lineItems[].quantity | M | Quantity invoiced | 2.00 |
| Units of Measurement | lineItems[].unitCode | O | UN/ECE Rec 20 code | PCE |
| Line Item Taxable Amount | lineItems[].lineTaxableValue | M | Taxable line amount | 900.00 |
| VAT Category Code | lineItems[].taxCategory | M | VAT category (S,Z,E,O) | S |
| VAT Exemption Reason Code | lineItems[].taxExemptionReasonCode | M | Mandatory when exempt/zero-rated | VATEX-SA-EDU |
| VAT Exemption Reason Text | lineItems[].taxExemptionReason | M | Mandatory when exempt/zero-rated | Educational materials |
| VAT Rate On Line Item | lineItems[].taxRate | M | Tax rate percentage | 15.0 |
| Line Item VAT Amount | lineItems[].taxAmount | M | Line VAT amount | 135.00 |
| Line Item Total | lineItems[].lineTotal | M | Line total with tax | 1035.00 |
6) Totals
| User Field Name | GETS Field | Mandatory/Optional/Conditional | KSA Rule | Sample Values |
|---|
| Summation of Line Net Values | totals.totalLineTaxableAmount | M | Sum of all line taxable amounts | 1900.00 |
| Additional Discount at Document Level | allowancesAndCharges[isCharge=false].amount | M | Document allowance total | 100.00 |
| Total Taxable Amount Excluding VAT | totals.totalAmountExcludingTax | M | Before tax total | 1800.00 |
| VAT Total | totals.totalTaxAmount | M | Total VAT | 270.00 |
| Invoice Total Amount | totals.totalAmountIncludingTax | M | Total including VAT | 2070.00 |
| Pre-Paid Amount | totals.prepaidAmount | M | Prepaid amount total | 500.00 |
| Amount Due for Payment | totals.amountDue | M | Final due amount | 1570.00 |
7) Digital Signature Extensions
| User Field Name | GETS Field | Mandatory/Optional/Conditional | KSA Rule | Sample Values |
|---|
| Invoice Counter Value | extensions.sa_icv | M | Sequential counter | 125 |
| Previous Invoice Hash | extensions.sa_pih | M | Previous document hash | NWZlY2ViNjZm... |
| QR Code | extensions.sa_qrCode | M | Base64 QR data | AQEGAmTkZhY... |
| Digital Signature | extensions.sa_digitalSignature | M | Signature from ZATCA cert | MEQCIDg5OTVl... |
Code Lists Reference
KSA Document Types (ZATCA UBL 2.1)
| Code | Document Type | GETS base |
|---|
| 388 | Standard Tax Invoice (B2B/B2G) | tax_invoice |
| 381 | Credit Note (B2B/B2G) | credit_note |
| 383 | Debit Note (B2B/B2G) | debit_note |
| 388 | Simplified Tax Invoice (B2C) | simplified_invoice |
| 381 | Simplified Credit Note (B2C) | simplified_credit_note |
| 383 | Simplified Debit Note (B2C) | simplified_debit_note |
KSA Modifiers (Transaction Scenarios)
| Modifier | Description |
|---|
self_billed | Buyer creates invoice on seller's behalf (B2B/B2G only) |
export | Goods/services supplied outside KSA (B2B/B2G, zero-rated) |
summary | Aggregate/batch invoice covering multiple transactions |
nominal | Token/pro-forma amount (B2B/B2G) |
third_party | Invoice through intermediary agent |
continuous_supply | Ongoing/recurring services (period required) |
b2g | Business-to-government transaction |
Tax Category Codes (UNCL 5305)
| Code | Description |
|---|
| S | Standard rate (15% for KSA) |
| Z | Zero-rated goods |
| E | Exempt from tax |
| O | Out of scope |
Payment Means Codes (UNCL 4461)
| Code | Description |
|---|
| 10 | Cash |
| 20 | Cheque |
| 30 | Credit transfer |
| 42 | Promissory note |
| 48 | Credit card |
| 54 | Credit card (brand specific) |
| 55 | Debit card |
| 58 | SEPA credit transfer |
| 59 | SEPA direct debit |
See Also
