Saudi Arabia E-Invoicing and Fiscalization Mandates

Saudi Arabia has implemented one of the most comprehensive e-invoicing mandates in the Middle East through ZATCA's Fatoorah program. This section outlines the mandate requirements affecting businesses operating in the Kingdom.

ZATCA Fatoorah eInvoicing

The Zakat, Tax and Customs Authority (ZATCA) introduced the Fatoorah (فاتورة) electronic invoicing mandate in two phases, establishing a Continuous Transaction Controls (CTC) system for real-time tax compliance.

What is Fatoorah?

Fatoorah is Saudi Arabia's mandatory e-invoicing system that requires businesses to generate, transmit, and store electronic invoices and related documents (credit/debit notes) through ZATCA-compliant solutions. In Phase 2, all invoices must be processed through ZATCA's Fatoora Portal via API before being shared with customers.

Regulatory Framework

Who Must Comply?

How It Works

The Saudi e-invoicing system operates through a CTC clearance and reporting model:

Both models require the use of an E-Invoicing Generation Solution (EGS) — a hardware or software system registered with ZATCA that generates cryptographically stamped invoices.

Document Types

The mandate covers several types of electronic documents:

Each document type can be issued as either:

• Standard (standard) — For B2B/B2G transactions, requires ZATCA clearance
• Simplified (simplified) — For B2C transactions, requires ZATCA reporting

Key Requirements

To comply with the ZATCA Fatoorah mandate, businesses must:

VAT Categories

Saudi Arabia supports four VAT categories for line items:

Implementation

Businesses should take the following steps to comply with the Fatoorah mandate:

For official compliance timelines and wave schedules, refer to the ZATCA e-invoicing portal.

ZATCA Fatoorah E-Invoicing with Flick

The ZATCA Fatoorah Phase 2 system requires businesses to integrate their invoicing solutions with ZATCA's Fatoora Portal for real-time clearance and reporting of electronic invoices.

What is ZATCA Phase 2?

Phase 2 (Integration Phase) of the Fatoorah mandate requires all applicable VAT-registered taxpayers to connect their E-Invoicing Generation Solutions (EGS) to ZATCA's Fatoora platform via API. This enables:

• B2B/B2G Clearance: Standard tax invoices must be submitted to ZATCA and cleared before delivery to the buyer
• B2C Reporting: Simplified tax invoices are reported to ZATCA within 24 hours of issuance
• Cryptographic Stamping: Every invoice is digitally signed using ZATCA-issued certificates

The Clearance and Reporting Model

ZATCA's system uses a Continuous Transaction Controls (CTC) model with two distinct flows depending on the transaction type:

Clearance Flow (B2B/B2G)

1. EGS generates the invoice in UBL 2.1 XML format
2. Invoice is digitally signed with the Production CSID
3. Invoice is submitted to ZATCA's Fatoora Portal via API
4. ZATCA validates the invoice against business rules
5. If valid, ZATCA returns the cleared invoice with a cryptographic stamp and QR code
6. The cleared invoice is delivered to the buyer

Reporting Flow (B2C)

1. EGS generates the simplified invoice in UBL 2.1 XML format
2. Invoice is digitally signed with the Production CSID
3. QR code is generated locally using TLV encoding
4. Invoice is issued to the customer immediately
5. Invoice data is reported to ZATCA via API within 24 hours

E-Invoicing Generation Solution (EGS)

An EGS is any hardware or software system used to generate electronic invoices. Each EGS device must be individually registered with ZATCA's Fatoora Portal and assigned its own cryptographic certificates.

EGS Requirements

EGS Integration Lifecycle

The full lifecycle from device registration through to live invoice generation:

Invoice Types

ZATCA defines two invoice types based on the transaction:

Standard Tax Invoice (B2B/B2G)

Simplified Tax Invoice (B2C)

Document Type Codes

Key Components

Cryptographic Stamp Identifier (CSID)

ZATCA issues digital certificates to each registered EGS device:

• Compliance CSID (CCSID): Temporary certificate issued during onboarding, used to complete compliance checks
• Production CSID (PCSID): Permanent certificate issued after passing compliance, used for live invoice signing

QR Code (TLV Encoding)

Phase 2 invoices require QR codes encoded using Tag-Length-Value (TLV) format containing:

1. Seller name (Arabic)
2. VAT registration number
3. Invoice timestamp (ISO 8601)
4. Invoice total (including VAT)
5. VAT amount
6. Invoice hash (Phase 2 only)
7. Digital signature (Phase 2 only)
8. Public key (Phase 2 only)
9. Certificate signature (Phase 2 only)

Standards and Format

For detailed API integration steps and code samples, refer to the eInvoicing Lifecycle and Examples sections.

ZATCA Invoice Datapoints

These are the datapoints used in the ZATCA e-invoicing API for generating and reporting invoices in Saudi Arabia.

Top-Level Invoice Fields

invoice_ref_number

Requirement: Mandatory
Type: String

Unique Invoice Reference Number. Must be sequential within your system.

{
  "invoice_ref_number": "INV-4"
}

Rules:

• Must be unique within the EGS device
• Should follow a sequential pattern
• Can include alphanumeric characters and hyphens

issue_date

Requirement: Mandatory
Type: Date (YYYY-MM-DD)

The date on which the invoice was issued.

{
  "issue_date": "2024-02-01"
}

Rules:

• Must be in ISO 8601 format: YYYY-MM-DD
• Cannot be a future date

issue_time

Requirement: Mandatory
Type: Time (HH:MM:SS)

The time at which the invoice was issued.

{
  "issue_time": "01:40:40"
}

Rules:

• Must be in 24-hour format: HH:MM:SS

doc_type

Requirement: Mandatory
Type: String

Specifies the type of document being issued.

{
  "doc_type": "388"
}

Allowed Values:

inv_type

Requirement: Mandatory
Type: String

Specifies whether this is a B2B or B2C invoice.

{
  "inv_type": "standard"
}

Allowed Values:

currency

Requirement: Optional
Type: String
Default: SAR

The currency in which the invoice was issued.

{
  "currency": "USD"
}

Rules:

• Must be a valid ISO 4217 currency code
• Default value is SAR
• If currency is not SAR, currency_exchange_rate must be provided

currency_exchange_rate

Requirement: Conditional
Type: Float

Exchange rate to SAR for the tax amount. Required when currency is not SAR.

{
  "currency": "USD",
  "currency_exchange_rate": 3.75
}

Rules:

• Required when currency is not SAR
• Represents the rate to convert 1 unit of the invoice currency to SAR

is_export

Requirement: Optional
Type: Boolean
Default: false

Indicates if this is an export transaction.

is_b2g

Requirement: Optional
Type: Boolean
Default: false

Indicates if this is a Business-to-Government (B2G) transaction.

is_thirdparty

Requirement: Optional
Type: Boolean
Default: false

Indicates if this is a third-party transaction.

is_nominal

Requirement: Optional
Type: Boolean
Default: false

Indicates if this is a nominal transaction.

is_summary

Requirement: Optional
Type: Boolean
Default: false

Indicates if this is a summary invoice.

is_selfbilled

Requirement: Optional
Type: Boolean
Default: false

Indicates if this is a self-billed invoice.

Party Details — party_details

Contains information about the customer (buyer) to whom the invoice is being issued.

party_name_ar

Requirement: Mandatory
Type: String

The name of the customer in Arabic.

{
  "party_details": {
    "party_name_ar": "شركة اختبار"
  }
}

party_name_en

Requirement: Optional
Type: String

The name of the customer in English.

{
  "party_details": {
    "party_name_en": "Test Company"
  }
}

party_vat

Requirement: Mandatory
Type: String

The VAT Registration number for the customer.

{
  "party_details": {
    "party_vat": "301121921500003"
  }
}

Rules:

• 15-digit number
• Starts and ends with 3

city_ar

Requirement: Mandatory
Type: String

Customer's city name in Arabic.

city_en

Requirement: Optional
Type: String

Customer's city name in English.

city_subdivision_ar

Requirement: Mandatory
Type: String

Customer's district or subdivision in Arabic.

city_subdivision_en

Requirement: Optional
Type: String

Customer's district or subdivision in English.

street_ar

Requirement: Mandatory
Type: String

Customer's street address in Arabic.

street_en

Requirement: Optional
Type: String

Customer's street address in English.

postal_zone

Requirement: Mandatory
Type: String

5-digit postal zone or ZIP code for the customer's location.

plot

Requirement: Optional
Type: String

4-digit plot identification number for the customer's location.

building

Requirement: Optional
Type: String

4-digit building number for the customer's location.

country

Requirement: Conditional
Type: String (ISO 3166-1 alpha-2)

Two-letter country code of the buyer. Defaults to SA if not provided. Mandatory for export invoices (is_export: true) or when the buyer is located outside Saudi Arabia.

{
  "party_details": {
    "country": "AE"
  }
}

party_add_id

Requirement: Optional
Type: Key-Value Object

Additional party identification. Can include IDs such as:

{
  "party_details": {
    "party_add_id": {
      "crn": "4123123431"
    }
  }
}

is_unregistered

Requirement: Optional
Type: Boolean
Default: false

Indicates if this is a VAT-unregistered party.

Full Party Details Example

{
  "party_details": {
    "party_name_ar": "شركة اختبار",
    "party_name_en": "Test Company",
    "party_vat": "301121921500003",
    "party_add_id": {
      "crn": "4123123431"
    },
    "city_ar": "جدة",
    "city_en": "Jeddah",
    "city_subdivision_ar": "البلد",
    "city_subdivision_en": "Al-Balad",
    "street_ar": "شارع فهد",
    "street_en": "Fahad St.",
    "building": "1234",
    "postal_zone": "12345"
  }
}

Line Items — lineitems[]

An array of items included in the invoice. At least one item is mandatory.

name_ar

Requirement: Mandatory
Type: String

The name of the item in Arabic.

name_en

Requirement: Optional
Type: String

The name of the item in English.

quantity

Requirement: Mandatory
Type: Float

The quantity of items included in the invoice.

tax_exclusive_price

Requirement: Mandatory
Type: Float

The price of the item exclusive of tax.

tax_percentage

Requirement: Mandatory
Type: Float

Tax percentage in decimal form (15% is given as 0.15).

tax_category

Requirement: Mandatory
Type: String

Specifies the VAT category for this line item.

tax_reason_code

Requirement: Conditional
Type: String

Required when tax_category is NOT S. The exemption reason code per UN/CEFACT code list 5305.

For "E" (Exempt from Tax):

For "Z" (Zero Rated):

For "O" (Out of Scope):

tax_reason_text

Requirement: Conditional
Type: String

Required when tax_category is NOT S. The human-readable reason text corresponding to tax_reason_code. Can be in English or Arabic.

discounts

Requirement: Optional
Type: Array of Objects

Line-item level discounts. Each discount has:

{
  "lineitems": [
    {
      "name_ar": "حاسوب محمول",
      "name_en": "Laptop",
      "quantity": 1,
      "tax_category": "S",
      "tax_exclusive_price": 1750,
      "tax_percentage": 0.15,
      "discounts": [
        {
          "amount": 50,
          "reason": "Loyalty discount"
        }
      ]
    }
  ]
}

Document-Level Discounts and Charges

Discounts

Requirement: Optional
Type: Array of Objects

Document-level discounts applied to the overall invoice total.

Charges

Requirement: Optional
Type: Array of Objects

Document-level charges or fees applied to the overall invoice total.

Both Discounts and Charges share the same schema:

{
  "Discounts": [
    {
      "amount": 100,
      "reason": "Flat Discount",
      "tax_category": "S",
      "tax_percentage": 0.15
    }
  ],
  "Charges": [
    {
      "amount": 50,
      "reason": "Service Fee",
      "tax_category": "S",
      "tax_percentage": 0.15
    }
  ]
}

Delivery Details — delivery_details

Requirement: Conditional
Type: Object

Delivery information related to the invoice. Mandatory when doc_type is 388 (Tax Invoice) and inv_type is standard.

{
  "delivery_details": {
    "actual_delivery": "2024-01-01",
    "latest_delivery": "2024-01-31"
  }
}

Advance Details — advance_details

Requirement: Conditional
Type: Object

Details related to advance amounts received against a final invoice. Only applicable when has_advance is true and doc_type is 388.

Advance Invoices — advance_invoices[]

Each entry represents a single advance invoice with its tax details and identification.

{
  "has_advance": true,
  "advance_details": {
    "advance_amount": 215,
    "advance_invoices": [
      {
        "tax_category": "S",
        "tax_percentage": 0.15,
        "taxable_amount": 100,
        "id": "ADV-INV-1",
        "issue_date": "2023-12-05",
        "issue_time": "12:34:23"
      },
      {
        "tax_category": "E",
        "tax_percentage": 0,
        "tax_reason_code": "VATEX-SA-29",
        "tax_reason_text": "Financial services mentioned in Article 29 of the VAT Regulations",
        "taxable_amount": 100,
        "id": "ADV-INV-2",
        "issue_date": "2023-12-06",
        "issue_time": "12:34:23"
      }
    ]
  }
}

Notes Details — notes_details

Requirement: Conditional
Type: Object

Required when doc_type is 381 (Credit Note) or 383 (Debit Note). Contains information about the original invoice being adjusted.

{
  "doc_type": "381",
  "notes_details": {
    "related_doc_reference": "INV-3",
    "reason_text": "Product return and refund"
  }
}

ZATCA eInvoicing Lifecycle

This guide covers the complete lifecycle of e-invoicing in Saudi Arabia, from onboarding EGS devices to generating, clearing, and reporting invoices through ZATCA's Fatoora Portal.

Overview

The ZATCA e-invoicing lifecycle follows these stages:

1. Onboard EGS Devices

Before generating invoices, your E-Invoicing Generation Solution (EGS) devices must be registered with ZATCA. This step generates a Compliance CSID (CCSID) for each device.

Prerequisites

• A Flick API account with KSA mandate enabled
• Your company's VAT registration details (15-digit VAT number starting and ending with 3)
• A 6-digit OTP obtained from the Fatoora Portal for each device

Request

Endpoint: POST /egs/onboard

Headers:

• x-flick-auth-key: Your Flick API key
• Content-Type: application/json

{
  "vat_name": "Test Co.",
  "vat_number": "300000000000003",
  "devices": [
    {
      "device_name": "TestEGS1",
      "city": "Riyadh",
      "city_subdiv": "Test Dist.",
      "street": "Test St.",
      "plot": "1234",
      "building": "1234",
      "postal": "12345",
      "branch_name": "Riyadh Branch 1",
      "branch_industry": "Retail",
      "otp": "123321"
    },
    {
      "device_name": "TestEGS2",
      "city": "Riyadh",
      "city_subdiv": "Test Dist.",
      "street": "Test St.",
      "plot": "1234",
      "building": "1234",
      "postal": "12345",
      "branch_name": "Riyadh Branch 2",
      "branch_industry": "Retail",
      "otp": "321123"
    }
  ]
}

Request Fields

Device Fields — devices[]

Each device in the array must include:

Response

{
  "status": "success",
  "data": {
    "response": [
      {
        "uuid": "f902f9aa-3d25-4bf2-90c5-6ec4bbc122df",
        "device_name": "TestEGS1",
        "compliance_certificate": "-----BEGIN CERTIFICATE-----\nMIICRT...2mx9I+et/byhTsH\n-----END CERTIFICATE-----"
      },
      {
        "uuid": "5cd9c201-1960-4bdd-9741-88a124c6a63b",
        "device_name": "TestEGS2",
        "compliance_certificate": "-----BEGIN CERTIFICATE-----\nMIICRT...2mx9I+et/byhTsH\n-----END CERTIFICATE-----"
      }
    ]
  }
}

Response Fields

Key Points:

• Each device gets its own UUID and Compliance CSID
• The UUID is required for the compliance check step and as a header when generating invoices
• You can onboard multiple devices in a single request
• For Group-VAT members, set branch_name to the member's 10-digit TIN

2. Complete Compliance Check

After onboarding, each EGS device must pass ZATCA's compliance checks to receive a Production CSID (PCSID). The compliance check verifies that the device can properly generate, sign, and submit invoices.

Request

Endpoint: GET /egs/compliance-check/{egs_uuid}

Headers:

• x-flick-auth-key: Your Flick API key

Path Parameters:

Sample Request

GET /egs/compliance-check/f902f9aa-3d25-4bf2-90c5-6ec4bbc122df

Response

{
  "status": "success",
  "data": {
    "response": {
      "uuid": "f902f9aa-3d25-4bf2-90c5-6ec4bbc122df",
      "device_name": "TestEGS1",
      "production_certificate": "-----BEGIN CERTIFICATE-----\nMIIFFTCCBLqgAwIBAgITGQAAE0B6Q1...jxMYAEr29G\n-----END CERTIFICATE-----"
    }
  }
}

Response Fields

Key Points:

• Each EGS device must complete this check individually
• The compliance check runs automated test invoices against ZATCA's validation rules
• Once a Production CSID is issued, the device can generate and submit live invoices
• Store the Production CSID securely — it is required for signing invoices

3. Generate E-Invoice

Generate an e-invoice and submit it to ZATCA for clearance (B2B) or prepare it for reporting (B2C).

Request

Endpoint: POST /api/einvoice/generate/invoice

Headers:

• x-flick-auth-key: Your Flick API key
• egs_uuid: UUID of the EGS device generating this invoice
• Content-Type: application/json

Standard Invoice (B2B)

{
  "invoice_ref_number": "INV-4",
  "issue_date": "2024-02-01",
  "issue_time": "01:40:40",
  "doc_type": "388",
  "currency": "USD",
  "currency_exchange_rate": 3.75,
  "inv_type": "standard",
  "party_details": {
    "party_name_ar": "شركة اختبار",
    "party_name_en": "Test Company",
    "party_vat": "301121921500003",
    "party_add_id": {
      "crn": "4123123431"
    },
    "city_ar": "جدة",
    "city_en": "Jeddah",
    "city_subdivision_ar": "البلد",
    "city_subdivision_en": "Al-Balad",
    "street_ar": "شارع فهد",
    "street_en": "Fahad St.",
    "building": "1234",
    "postal_zone": "12345"
  },
  "delivery_details": {
    "actual_delivery": "2024-01-01",
    "latest_delivery": "2024-01-31"
  },
  "has_advance": true,
  "advance_details": {
    "advance_amount": 215,
    "advance_invoices": [
      {
        "tax_category": "S",
        "tax_percentage": 0.15,
        "taxable_amount": 100,
        "id": "ADV-INV-1",
        "issue_date": "2023-12-05",
        "issue_time": "12:34:23"
      },
      {
        "tax_category": "E",
        "tax_percentage": 0,
        "tax_reason_code": "VATEX-SA-29",
        "tax_reason_text": "Financial services mentioned in Article 29 of the VAT Regulations",
        "taxable_amount": 100,
        "id": "ADV-INV-2",
        "issue_date": "2023-12-06",
        "issue_time": "12:34:23"
      }
    ]
  },
  "lineitems": [
    {
      "name_en": "Laptop",
      "name_ar": "حاسوب محمول",
      "quantity": 1,
      "tax_category": "S",
      "tax_exclusive_price": 1750,
      "tax_percentage": 0.15
    },
    {
      "name_en": "Iphone",
      "name_ar": "ايفون",
      "quantity": 1,
      "tax_category": "S",
      "tax_exclusive_price": 750,
      "tax_percentage": 0.15
    }
  ]
}

Success Response (200)

{
  "status": "success",
  "data": {
    "uuid": "be90ce5a-0870-48cb-99d9-281a72267bd0",
    "invoice_hash": "gwu7kxui55r3v0ZKa2zHKkJogrtVjnK5WJa6QkkaVfU=",
    "invoice_total": 3191.5,
    "tax_total": "322.50",
    "qr_code": "AStNdXRhYmFxYW5pIE1lZGlj...",
    "pdf_base64": "JVBERi0xLjQKMSAwIG9iago8P...",
    "xml_base64": "PD94bWwgdmVyc2lvbj0iMS4w..."
  }
}

Response Fields

Validation Error Response (400)

{
  "status": "validation_error",
  "message": "There are validation errors in the submitted data",
  "errors": [
    {
      "error": "Issue time is required",
      "path": ["issue_time"]
    }
  ],
  "errors_text": "(1) Issue time is required"
}

Request Fields Summary

4. Report B2C E-Invoice

Use this endpoint when you do not need real-time clearance. Instead of clearing the invoice through ZATCA before delivery, the /report endpoint returns a QR code immediately so you can issue it to the customer (e.g. from a POS system), while Flick reports the transaction to ZATCA asynchronously within 24 hours.

This is the standard flow for simplified (B2C) invoices.

Request

Endpoint: POST /api/einvoice/report

Headers:

• x-flick-auth-key: Your Flick API key
• egs_uuid: UUID of the EGS device
• Content-Type: application/json

The request body is the same as the Generate endpoint. For B2C invoices, use inv_type: "simplified" and party_details are optional.

{
  "invoice_ref_number": "INV-2",
  "issue_date": "2023-01-01",
  "issue_time": "01:40:40",
  "doc_type": "388",
  "inv_type": "simplified",
  "currency": "SAR",
  "lineitems": [
    {
      "name_en": "Laptop",
      "name_ar": "كمبيوتر محمول",
      "quantity": 1,
      "tax_category": "S",
      "tax_exclusive_price": 1750,
      "tax_percentage": 0.15
    }
  ]
}

Success Response (200)

{
  "uuid": "cf1f175d-a614-484a-a4ec-6754677c6859",
  "invoice_hash": "rK/NAM9Wy9BVEWI7V7J3o3XNp10Dsjb3qZGPyxBA06s=",
  "qr_code": "ARlBbCBTYWRoYW4gVHJhZGluZyBDb21wYW55..."
}

Response Fields

Validation Error Response (400)

Validation errors follow the same structure as the Generate endpoint. See Generate Validation Error above.

Key Differences: Generate vs Report

5. Generate Phase One QR Code

For businesses still in Phase 1, or for generating standalone QR codes, use this endpoint to create a ZATCA-compliant QR code with the 5 mandatory TLV fields.

Request

Endpoint: POST /api/einvoice/generate/phase-one-qr

Headers:

• x-flick-auth-key: Your Flick API key
• Content-Type: application/json

{
  "seller_vat": "300000000000033",
  "seller_name": "شركة اختبار",
  "issue_date": "2024-02-01",
  "issue_time": "01:40:40",
  "invoice_total": 1200,
  "tax_total": 200
}

Response

{
  "status": "success",
  "data": {
    "seller_vat": "300000000000033",
    "invoice_total": 1200,
    "qr_code": "AQzYs9in2K/Yrdin2YYCDzMwMDAwMDAwMDAwMDAzMwMUMjAyNC0wMi0wMVQwMTo0MDo0MFoEBDEyMDAFAzIwMA=="
  }
}

Response Fields

Complete Integration Flow

Here is the recommended sequence for a full integration:

Initial Setup (One-time)

1. Get API credentials from the Flick dashboard
2. Obtain OTPs from the Fatoora Portal for each EGS device
3. Onboard devices via POST /egs/onboard — save the returned UUIDs
4. Complete compliance via GET /egs/compliance-check/{uuid} — obtain Production CSIDs

Ongoing Operations

5. Generate B2B invoices via POST /api/einvoice/generate/invoice with inv_type: "standard"
6. Report B2C invoices via POST /api/einvoice/report with inv_type: "simplified"
7. Handle errors — check response status and handle ZATCA rejections

Integration Checklist

Before going live, verify:

• All EGS devices are onboarded and have Production CSIDs
• API authentication is configured with valid credentials
• B2B invoices are being cleared before delivery to buyers
• B2C invoices are being reported within 24 hours
• VAT calculations are correct (15% standard rate)
• Arabic fields (name_ar, city_ar, etc.) are properly encoded in UTF-8
• Sequential invoice numbering is maintained per EGS device
• Error handling and retry logic are implemented
• Sandbox testing is complete with all invoice types

For complete request body examples covering all invoice types, refer to the Examples section.

Saudi Arabia E-Invoicing Examples

Complete collection of ZATCA-compliant invoice examples covering standard invoices, simplified invoices, credit/debit notes, advance invoices, and special scenarios.

Standard Invoices

Standard Tax Invoice (B2B)

A typical B2B tax invoice with standard 15% VAT rate, full buyer details, and multiple line items.

Key Features:

• Document Type: 388 (Tax Invoice)
• Invoice Type: standard (B2B — requires ZATCA clearance)
• Standard VAT rate: 15%
• Full party details with Arabic and English names

{
  "invoice_ref_number": "INV-001",
  "issue_date": "2024-02-01",
  "issue_time": "14:30:00",
  "doc_type": "388",
  "inv_type": "standard",
  "currency": "SAR",
  "party_details": {
    "party_name_ar": "شركة التقنية المحدودة",
    "party_name_en": "Tech Solutions Ltd.",
    "party_vat": "301121921500003",
    "party_add_id": {
      "crn": "4123123431"
    },
    "city_ar": "الرياض",
    "city_en": "Riyadh",
    "city_subdivision_ar": "العليا",
    "city_subdivision_en": "Al Olaya",
    "street_ar": "طريق الملك فهد",
    "street_en": "King Fahd Road",
    "building": "1234",
    "plot": "5678",
    "postal_zone": "12345"
  },
  "delivery_details": {
    "actual_delivery": "2024-02-01",
    "latest_delivery": "2024-02-28"
  },
  "lineitems": [
    {
      "name_en": "Software Development Services",
      "name_ar": "خدمات تطوير البرمجيات",
      "quantity": 100,
      "tax_category": "S",
      "tax_exclusive_price": 500,
      "tax_percentage": 0.15
    },
    {
      "name_en": "Technical Support",
      "name_ar": "الدعم الفني",
      "quantity": 50,
      "tax_category": "S",
      "tax_exclusive_price": 200,
      "tax_percentage": 0.15
    }
  ]
}

Simplified Tax Invoice (B2C)

A B2C point-of-sale invoice. Buyer details are optional for simplified invoices.

Key Features:

• Document Type: 388 (Tax Invoice)
• Invoice Type: simplified (B2C — reported to ZATCA after issuance)
• No buyer details required
• QR code generated locally

{
  "invoice_ref_number": "POS-001",
  "issue_date": "2024-02-01",
  "issue_time": "10:15:30",
  "doc_type": "388",
  "inv_type": "simplified",
  "currency": "SAR",
  "lineitems": [
    {
      "name_en": "Laptop",
      "name_ar": "حاسوب محمول",
      "quantity": 1,
      "tax_category": "S",
      "tax_exclusive_price": 4500,
      "tax_percentage": 0.15
    },
    {
      "name_en": "Wireless Mouse",
      "name_ar": "فأرة لاسلكية",
      "quantity": 2,
      "tax_category": "S",
      "tax_exclusive_price": 150,
      "tax_percentage": 0.15
    }
  ]
}

Credit Notes and Debit Notes

Credit Note

A credit note that adjusts (reduces) a previously issued invoice. Used for returns, corrections, or partial refunds.

Key Features:

• Document Type: 381 (Credit Note)
• Requires notes_details with reference to the original invoice
• Can be standard or simplified based on the original invoice type

{
  "invoice_ref_number": "CN-001",
  "issue_date": "2024-02-15",
  "issue_time": "09:00:00",
  "doc_type": "381",
  "inv_type": "standard",
  "currency": "SAR",
  "notes_details": {
    "related_doc_reference": "INV-001",
    "reason_text": "Product return - defective item"
  },
  "party_details": {
    "party_name_ar": "شركة التقنية المحدودة",
    "party_name_en": "Tech Solutions Ltd.",
    "party_vat": "301121921500003",
    "city_ar": "الرياض",
    "city_en": "Riyadh",
    "city_subdivision_ar": "العليا",
    "city_subdivision_en": "Al Olaya",
    "street_ar": "طريق الملك فهد",
    "street_en": "King Fahd Road",
    "postal_zone": "12345"
  },
  "lineitems": [
    {
      "name_en": "Laptop",
      "name_ar": "حاسوب محمول",
      "quantity": 1,
      "tax_category": "S",
      "tax_exclusive_price": 4500,
      "tax_percentage": 0.15
    }
  ]
}

Debit Note

A debit note that adjusts (increases) a previously issued invoice. Used for additional charges or corrections.

Key Features:

• Document Type: 383 (Debit Note)
• Requires notes_details with reference to the original invoice

{
  "invoice_ref_number": "DN-001",
  "issue_date": "2024-02-15",
  "issue_time": "11:30:00",
  "doc_type": "383",
  "inv_type": "standard",
  "currency": "SAR",
  "notes_details": {
    "related_doc_reference": "INV-001",
    "reason_text": "Additional installation services"
  },
  "party_details": {
    "party_name_ar": "شركة التقنية المحدودة",
    "party_name_en": "Tech Solutions Ltd.",
    "party_vat": "301121921500003",
    "city_ar": "الرياض",
    "city_en": "Riyadh",
    "city_subdivision_ar": "العليا",
    "city_subdivision_en": "Al Olaya",
    "street_ar": "طريق الملك فهد",
    "street_en": "King Fahd Road",
    "postal_zone": "12345"
  },
  "lineitems": [
    {
      "name_en": "Installation Service",
      "name_ar": "خدمة التركيب",
      "quantity": 1,
      "tax_category": "S",
      "tax_exclusive_price": 500,
      "tax_percentage": 0.15
    }
  ]
}

Advance Invoice

An advance invoice issued for advance payments received before delivery of goods or services.

Key Features:

• Document Type: 386 (Advance Invoice)
• No advance_details needed — this IS the advance invoice itself

{
  "invoice_ref_number": "ADV-001",
  "issue_date": "2024-01-15",
  "issue_time": "12:00:00",
  "doc_type": "386",
  "inv_type": "standard",
  "currency": "SAR",
  "party_details": {
    "party_name_ar": "شركة البناء السعودية",
    "party_name_en": "Saudi Construction Co.",
    "party_vat": "300456789000003",
    "city_ar": "جدة",
    "city_en": "Jeddah",
    "city_subdivision_ar": "الحمراء",
    "city_subdivision_en": "Al Hamra",
    "street_ar": "شارع الأمير سلطان",
    "street_en": "Prince Sultan St.",
    "postal_zone": "21577"
  },
  "lineitems": [
    {
      "name_en": "Advance Payment - Construction Project",
      "name_ar": "دفعة مقدمة - مشروع بناء",
      "quantity": 1,
      "tax_category": "S",
      "tax_exclusive_price": 50000,
      "tax_percentage": 0.15
    }
  ]
}

Final Invoice with Advance Deduction

A final invoice that deducts a previously paid advance. Uses has_advance and advance_details to reference prior advance invoices.

Key Features:

• Document Type: 388 (Tax Invoice)
• has_advance: true with advance_details referencing prior advance invoices
• Each advance invoice listed individually with its tax category

{
  "invoice_ref_number": "INV-005",
  "issue_date": "2024-03-01",
  "issue_time": "09:00:00",
  "doc_type": "388",
  "inv_type": "standard",
  "currency": "SAR",
  "party_details": {
    "party_name_ar": "شركة البناء السعودية",
    "party_name_en": "Saudi Construction Co.",
    "party_vat": "300456789000003",
    "city_ar": "جدة",
    "city_en": "Jeddah",
    "city_subdivision_ar": "الحمراء",
    "city_subdivision_en": "Al Hamra",
    "street_ar": "شارع الأمير سلطان",
    "street_en": "Prince Sultan St.",
    "postal_zone": "21577"
  },
  "has_advance": true,
  "advance_details": {
    "advance_amount": 57500,
    "advance_invoices": [
      {
        "tax_category": "S",
        "tax_percentage": 0.15,
        "taxable_amount": 50000,
        "id": "ADV-001",
        "issue_date": "2024-01-15",
        "issue_time": "12:00:00"
      }
    ]
  },
  "lineitems": [
    {
      "name_en": "Construction Services - Phase 1",
      "name_ar": "خدمات البناء - المرحلة الأولى",
      "quantity": 1,
      "tax_category": "S",
      "tax_exclusive_price": 200000,
      "tax_percentage": 0.15
    }
  ]
}

Multi-Currency Invoice

An invoice issued in a foreign currency with an exchange rate to SAR.

Key Features:

• Currency set to USD instead of default SAR
• currency_exchange_rate provides the conversion rate for tax calculations

{
  "invoice_ref_number": "INV-006",
  "issue_date": "2024-02-01",
  "issue_time": "01:40:40",
  "doc_type": "388",
  "currency": "USD",
  "currency_exchange_rate": 3.75,
  "inv_type": "standard",
  "party_details": {
    "party_name_ar": "شركة اختبار",
    "party_name_en": "Test Company",
    "party_vat": "301121921500003",
    "party_add_id": {
      "crn": "4123123431"
    },
    "city_ar": "جدة",
    "city_en": "Jeddah",
    "city_subdivision_ar": "البلد",
    "city_subdivision_en": "Al-Balad",
    "street_ar": "شارع فهد",
    "street_en": "Fahad St.",
    "building": "1234",
    "postal_zone": "12345"
  },
  "lineitems": [
    {
      "name_en": "Consulting Services",
      "name_ar": "خدمات استشارية",
      "quantity": 10,
      "tax_category": "S",
      "tax_exclusive_price": 500,
      "tax_percentage": 0.15
    }
  ]
}

Export Invoice

An invoice for exported goods or services, with zero-rated VAT.

Key Features:

• is_export: true flag set
• Line items use tax category Z (Zero Rated) with reason code VATEX-SA-32 or VATEX-SA-33

{
  "invoice_ref_number": "EXP-001",
  "issue_date": "2024-02-01",
  "issue_time": "08:00:00",
  "doc_type": "388",
  "inv_type": "standard",
  "currency": "USD",
  "currency_exchange_rate": 3.75,
  "is_export": true,
  "party_details": {
    "party_name_ar": "شركة أجنبية",
    "party_name_en": "Foreign Corp Inc.",
    "party_vat": "",
    "party_add_id": {
      "crn": "1234567890"
    },
    "city_ar": "دبي",
    "city_en": "Dubai",
    "city_subdivision_ar": "وسط المدينة",
    "city_subdivision_en": "Downtown",
    "street_ar": "شارع الشيخ زايد",
    "street_en": "Sheikh Zayed Rd.",
    "building": "1234",
    "postal_zone": "00000",
    "country": "AE",
    "is_unregistered": true
  },
  "lineitems": [
    {
      "name_en": "Software License - Annual",
      "name_ar": "ترخيص برمجي - سنوي",
      "quantity": 1,
      "tax_category": "Z",
      "tax_exclusive_price": 10000,
      "tax_percentage": 0,
      "tax_reason_code": "VATEX-SA-33",
      "tax_reason_text": "Export of services"
    }
  ]
}

Invoice with Document-Level Discounts and Charges

An invoice that includes both document-level discounts and charges.

{
  "invoice_ref_number": "INV-007",
  "issue_date": "2024-02-01",
  "issue_time": "14:00:00",
  "doc_type": "388",
  "inv_type": "standard",
  "currency": "SAR",
  "party_details": {
    "party_name_ar": "شركة المشتري",
    "party_name_en": "Buyer Corp.",
    "party_vat": "301121921500003",
    "city_ar": "الرياض",
    "city_en": "Riyadh",
    "city_subdivision_ar": "المروج",
    "city_subdivision_en": "Al Muruj",
    "street_ar": "شارع التحلية",
    "street_en": "Tahlia St.",
    "postal_zone": "12345"
  },
  "lineitems": [
    {
      "name_en": "Product A",
      "name_ar": "منتج أ",
      "quantity": 10,
      "tax_category": "S",
      "tax_exclusive_price": 100,
      "tax_percentage": 0.15
    },
    {
      "name_en": "Product B",
      "name_ar": "منتج ب",
      "quantity": 5,
      "tax_category": "S",
      "tax_exclusive_price": 200,
      "tax_percentage": 0.15
    }
  ],
  "Discounts": [
    {
      "amount": 100,
      "reason": "Volume discount",
      "tax_category": "S",
      "tax_percentage": 0.15
    }
  ],
  "Charges": [
    {
      "amount": 50,
      "reason": "Delivery fee",
      "tax_category": "S",
      "tax_percentage": 0.15
    }
  ]
}

Exempt and Zero-Rated Items

Invoice with Exempt Items

{
  "invoice_ref_number": "INV-008",
  "issue_date": "2024-02-01",
  "issue_time": "10:00:00",
  "doc_type": "388",
  "inv_type": "standard",
  "currency": "SAR",
  "party_details": {
    "party_name_ar": "بنك المملكة",
    "party_name_en": "Kingdom Bank",
    "party_vat": "300789456000003",
    "city_ar": "الرياض",
    "city_en": "Riyadh",
    "city_subdivision_ar": "الملز",
    "city_subdivision_en": "Al Malaz",
    "street_ar": "شارع العروبة",
    "street_en": "Uruba St.",
    "postal_zone": "11461"
  },
  "lineitems": [
    {
      "name_en": "Financial Advisory Services",
      "name_ar": "خدمات الاستشارات المالية",
      "quantity": 1,
      "tax_category": "E",
      "tax_exclusive_price": 25000,
      "tax_percentage": 0,
      "tax_reason_code": "VATEX-SA-29",
      "tax_reason_text": "Financial services mentioned in Article 29 of the VAT Regulations"
    }
  ]
}

Invoice with Zero-Rated Items (Medical Supplies)

{
  "invoice_ref_number": "INV-009",
  "issue_date": "2024-02-01",
  "issue_time": "11:30:00",
  "doc_type": "388",
  "inv_type": "standard",
  "currency": "SAR",
  "party_details": {
    "party_name_ar": "مستشفى المملكة",
    "party_name_en": "Kingdom Hospital",
    "party_vat": "300111222000003",
    "city_ar": "الرياض",
    "city_en": "Riyadh",
    "city_subdivision_ar": "السليمانية",
    "city_subdivision_en": "Al Sulaimaniyyah",
    "street_ar": "شارع صلاح الدين",
    "street_en": "Salahuddin St.",
    "postal_zone": "11564"
  },
  "lineitems": [
    {
      "name_en": "Medical Equipment - MRI Scanner",
      "name_ar": "معدات طبية - جهاز تصوير بالرنين المغناطيسي",
      "quantity": 1,
      "tax_category": "Z",
      "tax_exclusive_price": 500000,
      "tax_percentage": 0,
      "tax_reason_code": "VATEX-SA-35",
      "tax_reason_text": "Medicines and medical equipment"
    }
  ]
}

VAT Category Reference

Tax Categories

Exemption Reason Codes

Zero Rated (Z)

Exempt (E)

Out of Scope (O)

Document Type Reference

Best Practices

1. Always test in sandbox first — Use the sandbox environment before processing live invoices
2. Maintain sequential numbering — Invoice reference numbers must be sequential per EGS device
3. Include Arabic fields — All _ar fields are mandatory; _en fields are optional but recommended
4. Validate VAT numbers — Ensure all VAT numbers are 15 digits, starting and ending with 3
5. Use correct tax categories — Always provide tax_reason_code and tax_reason_text for non-standard (Z, E, O) categories
6. Report B2C promptly — Simplified invoices must be reported to ZATCA within 24 hours

For detailed field definitions, refer to Invoice Datapoints. For the complete integration flow, see eInvoicing Lifecycle.