Saudi Arabia (SA) Field Mapping

Country: SA Compliance: ZATCA e-invoicing Last Updated: 2026

This page includes the full Saudi Arabia field mapping with actual JSON field paths and SA country extension fields in one place.

Complete Sample Payload

{
  "invoice_data": {
    "invoice_number": "INV-20251212143045123",
    "invoice_date": "2025-12-11",
    "invoice_time": "14:30:00.000",
    "currency_code": "SAR",
    "total_amount": 23000.0,
    "total_payable_amount": 23000.0,
    "tax_exclusive_amount": 20000.0,
    "line_extension_amount": 20000.0,
    "total_tax_amount": 3000.0,
    "paid_amount": 0,
    "invoice_endDate": "2025-12-11",
    "invoice_startDate": "2025-12-11",
    "vat_currency_code": "SAR",
    "exchange_percentage": 1,
    "invoice_due_date": "2026-01-11",
    "total_discount": "0",
    "PaymentMethod": "CASH"
  },
  "seller_info": {
    "company_name": "Advanced Tech Solutions LLC",
    "vat_registration": "310123456700003",
    "tax_scheme": "VAT",
    "street_address": "King Fahd Road",
    "additional_address_info": "Building 123",
    "building_number": "1234",
    "district_name": "Al Olaya",
    "city_name": "Riyadh",
    "state_name": "Riyadh Province",
    "postal_code": "11564",
    "country_code": "SA",
    "seller_id": "2034567890",
    "phone": "+966501234567",
    "email": "contact@advancedtech.sa",
    "contact_name": "Ahmed Al-Rashid",
    "Crn_number": "2034567890",
    "Additional_Type": "CRN"
  },
  "buyer_info": {
    "buyer_name": "Global Manufacturing Co.",
    "buyer_vat": "310987654300003",
    "buyer_tax_scheme": "VAT",
    "buyer_address": "Industrial City",
    "buyer_additional_address_info": "Block A",
    "buyer_building": "4567",
    "buyer_district": "Industrial Area",
    "buyer_city": "Dammam",
    "buyer_state": "Damman Province",
    "buyer_postal": "31461",
    "buyer_country": "SA",
    "buyer_id": "2034567890",
    "crn_Number": "2034567890",
    "Additional_Type": "CRN"
  },
  "line_items": [
    {
      "item_id": "ITEM001",
      "item_name": "Industrial Server System",
      "quantity": "2",
      "unit_code": "PCE",
      "unit_price": "8500.00",
      "tax_amount": "2550.00",
      "tax_category": "S",
      "tax_rate": "15",
      "discount_amount": "0",
      "sub_Total": "19550",
      "taxable_amount": "17000"
    },
    {
      "item_id": "ITEM002",
      "item_name": "Network Security Module",
      "quantity": "1",
      "unit_code": "PCE",
      "unit_price": "3000.00",
      "tax_amount": "450.00",
      "tax_category": "S",
      "tax_rate": "15",
      "discount_amount": "0",
      "sub_Total": "3450",
      "taxable_amount": "3000"
    }
  ],
  "extensions": {
    "sa_prepayment": [
      {
        "paymentId": "PP-2024-001",
        "issueDate": "2024-01-15T14:30:00Z",
        "documentType": "tax_invoice_prepayment_invoice",
        "vatCategory": "S",
        "vatRate": 15.0,
        "taxableAmount": 1000.0,
        "taxAmount": 150.0,
        "adjustmentAmount": 1150.0
      }
    ]
  },
  "destinations": [
    {
      "type": "tax_authority",
      "details": {
        "authority": "ZATCA",
        "country": "SA",
        "document_type": "tax_invoice"
      }
    }
  ],
  "additional_data": {
    "order_reference": "PO-2024-5678",
    "delivery_date": "2024-01-20",
    "source_system": "test-source-11111111"
  }
}

Field Mapping Reference

Use the tables below to map your data to the correct JSON field paths. All paths use dot notation.

Document Header Fields

JSON Field Path	Type	Required	Description	Example
`invoice_data.invoice_number`	string	Yes	Unique invoice number. Must follow ZATCA format.	`INV-20251212143045123`
`invoice_data.invoice_date`	string	Yes	Invoice issue date (YYYY-MM-DD).	`2025-12-11`
`invoice_data.invoice_time`	string	Yes	Invoice issue time (HH:MM:SS.SSS).	`14:30:00.000`
`invoice_data.currency_code`	string	Yes	Currency code (ISO 4217). Defaults to SAR.	`SAR`
`invoice_data.total_amount`	number	Yes	Final amount including VAT.	`23000.0`
`invoice_data.total_payable_amount`	number	Yes	Total amount due for payment.	`23000.0`
`invoice_data.tax_exclusive_amount`	number	Yes	Total amount excluding VAT.	`20000.0`
`invoice_data.line_extension_amount`	number	Yes	Sum of line amounts before VAT.	`20000.0`
`invoice_data.total_tax_amount`	number	Yes	Total VAT amount.	`3000.0`
`invoice_data.paid_amount`	number	No	Prepaid amount.	`0`
`invoice_data.invoice_endDate`	string	No	Invoice period end date.	`2025-12-11`
`invoice_data.invoice_startDate`	string	No	Invoice period start date.	`2025-12-11`
`invoice_data.vat_currency_code`	string	No	VAT currency code. Defaults to SAR.	`SAR`
`invoice_data.exchange_percentage`	number	No	Exchange rate (1 for SAR).	`1`
`invoice_data.invoice_due_date`	string	No	Payment due date.	`2026-01-11`
`invoice_data.total_discount`	string	No	Total discount amount.	`0`
`invoice_data.PaymentMethod`	string	No	Payment method (`CASH`, `CREDIT`).	`CASH`

Seller Information Fields

JSON Field Path	Type	Required	Description	Example
`seller_info.company_name`	string	Yes	Legal registered name. Must match ZATCA registration.	`Advanced Tech Solutions LLC`
`seller_info.vat_registration`	string	Yes	KSA VAT number (15 digits, starts with 3).	`310123456700003`
`seller_info.tax_scheme`	string	Yes	Tax identification scheme (`VAT`).	`VAT`
`seller_info.street_address`	string	Yes	Primary street address.	`King Fahd Road`
`seller_info.additional_address_info`	string	No	Additional address info.	`Building 123`
`seller_info.building_number`	string	Yes	Building number (4 digits for KSA).	`1234`
`seller_info.district_name`	string	Yes	District/neighbourhood name.	`Al Olaya`
`seller_info.city_name`	string	Yes	City name.	`Riyadh`
`seller_info.state_name`	string	Yes	State/province name.	`Riyadh Province`
`seller_info.postal_code`	string	Yes	Postal code (5 digits or 5+4 format).	`11564`
`seller_info.country_code`	string	Yes	Country code (must be `SA`).	`SA`
`seller_info.seller_id`	string	No	Internal seller identifier.	`2034567890`
`seller_info.phone`	string	No	Contact phone number.	`+966501234567`
`seller_info.email`	string	No	Contact email address.	`contact@advancedtech.sa`
`seller_info.contact_name`	string	No	Contact person name.	`Ahmed Al-Rashid`
`seller_info.Crn_number`	string	Yes	Commercial Registration Number (CRN).	`2034567890`
`seller_info.Additional_Type`	string	Yes	Registration type (`CRN`).	`CRN`

Buyer Information Fields (B2B)

JSON Field Path	Type	Required	Description	Example
`buyer_info.buyer_name`	string	Conditional	Buyer legal name. Required for B2B.	`Global Manufacturing Co.`
`buyer_info.buyer_vat`	string	Conditional	Buyer VAT number (15 digits). Required for B2B.	`310987654300003`
`buyer_info.buyer_tax_scheme`	string	Yes	Tax identification scheme.	`VAT`
`buyer_info.buyer_address`	string	Yes	Buyer street address.	`Industrial City`
`buyer_info.buyer_additional_address_info`	string	No	Additional address line.	`Block A`
`buyer_info.buyer_building`	string	No	Buyer building number.	`4567`
`buyer_info.buyer_district`	string	No	Buyer district/neighbourhood.	`Industrial Area`
`buyer_info.buyer_city`	string	Yes	Buyer city name.	`Dammam`
`buyer_info.buyer_state`	string	No	Buyer state/province.	`Damman Province`
`buyer_info.buyer_postal`	string	Yes	Buyer postal code.	`31461`
`buyer_info.buyer_country`	string	Yes	Country code (must be `SA`).	`SA`
`buyer_info.buyer_id`	string	No	Internal buyer identifier.	`2034567890`
`buyer_info.crn_Number`	string	No	Buyer commercial registration number.	`2034567890`
`buyer_info.Additional_Type`	string	No	Buyer registration type.	`CRN`

Line Items Fields

JSON Field Path	Type	Required	Description	Example
`line_items[].item_id`	string	Yes	Unique line identifier.	`ITEM001`
`line_items[].item_name`	string	Yes	Item/product name.	`Industrial Server System`
`line_items[].quantity`	string	Yes	Invoiced quantity.	`2`
`line_items[].unit_code`	string	Yes	Unit of measurement (UN/ECE Rec 20).	`PCE`
`line_items[].unit_price`	string	Yes	Price per unit.	`8500.00`
`line_items[].tax_amount`	string	Yes	VAT amount for this line.	`2550.00`
`line_items[].tax_category`	string	Yes	VAT category (`S`=Standard 15%, `Z`=Zero, `E`=Exempt, `O`=Out of scope).	`S`
`line_items[].tax_rate`	string	Yes	VAT rate percentage (15 for standard).	`15`
`line_items[].discount_amount`	string	No	Line-level discount amount.	`0`
`line_items[].sub_Total`	string	No	Line subtotal including VAT.	`19550`
`line_items[].taxable_amount`	string	Yes	Taxable amount (quantity × unit price - discount).	`17000`

Totals and Amounts Fields

JSON Field Path	Type	Required	Description	Example
`invoice_data.total_amount`	number	Yes	Total amount including VAT.	`23000.0`
`invoice_data.total_payable_amount`	number	Yes	Final amount due.	`23000.0`
`invoice_data.tax_exclusive_amount`	number	Yes	Total excluding VAT.	`20000.0`
`invoice_data.line_extension_amount`	number	Yes	Sum of line amounts before VAT.	`20000.0`
`invoice_data.total_tax_amount`	number	Yes	Total VAT amount.	`3000.0`

Payment Details Fields

JSON Field Path	Type	Required	Description	Example
`payment_details.payment_means`	string	No	Payment means code (UN/ECE 4461).	`42`
`payment_details.payment_terms`	string	No	Payment terms description.	`Net 30 days`
`payment_details.due_date`	string	No	Payment due date.	`2024-02-14`
`payment_details.bank_account`	string	No	IBAN for payment. Format: SA + 22 digits.	`SA9608000000123456789012`
`payment_details.payment_reference`	string	No	Payment reference number.	`PAY-2024-001234`

Country Extension Fields

Saudi Arabia-specific prepayment extension fields.

JSON Field Path	Type	Required	Description	Example
`extensions.sa_prepayment[].paymentId`	string	Conditional	Prepayment payment ID.	`PP-2024-001`
`extensions.sa_prepayment[].issueDate`	string	Conditional	Prepayment issue date/time.	`2024-01-15T14:30:00Z`
`extensions.sa_prepayment[].documentType`	string	Conditional	Document type (`386` for prepayment).	`tax_invoice_prepayment_invoice`
`extensions.sa_prepayment[].vatCategory`	string	Conditional	VAT category code.	`S`
`extensions.sa_prepayment[].vatRate`	number	Conditional	VAT rate percentage.	`15.0`
`extensions.sa_prepayment[].taxableAmount`	number	Conditional	Taxable amount for prepayment.	`1000.0`
`extensions.sa_prepayment[].taxAmount`	number	Conditional	VAT amount for prepayment.	`150.0`
`extensions.sa_prepayment[].adjustmentAmount`	number	Conditional	Adjustment amount.	`1150.0`

Destinations Fields

JSON Field Path	Type	Required	Description	Example
`destinations[].type`	string	Yes	Destination type (`tax_authority`).	`tax_authority`
`destinations[].details.authority`	string	Yes	Tax authority name (`ZATCA`).	`ZATCA`
`destinations[].details.country`	string	Yes	Country code.	`SA`
`destinations[].details.document_type`	string	Yes	Document type for submission.	`tax_invoice`

Additional Data Fields

JSON Field Path	Type	Required	Description	Example
`additional_data.order_reference`	string	No	Purchase order reference.	`PO-2024-5678`
`additional_data.delivery_date`	string	No	Delivery date.	`2024-01-20`
`additional_data.source_system`	string	No	Source system identifier.	`test-source-11111111`