Saudi Arabia (KSA) Implementation Examples

Complete ZATCA-compliant examples using the canonical GETS structure. Includes both the final GETS JSON format and Java SDK payload examples. All examples provide 100% field coverage for KSA requirements with bilingual support (English/Arabic).

Complete GETS Examples

Ready-to-use examples with full GETS structure and KSA compliance.

B2B Tax Invoice

Most Popular - Standard business-to-business tax invoice with all required KSA fields, bilingual descriptions, and GETS canonical structure.

{
  "header": {
    "invoiceId": "INV-2024-001",
    "issueDate": "2024-06-01",
    "issueTime": "10:00:00Z",
    "dueDate": "2024-06-15",
    "documentCurrency": "SAR",
    "supplyStartDate": "2024-06-01",
    "supplyEndDate": "2024-06-30",
    "documentType": "tax_invoice"
  },
  "parties": {
    "seller": {
      "name": { "en": "Acme Trading LLC", "ar": "شركة اكمي للتجارة" },
      "identifications": [
        { "id": "310122393500003", "schemeId": "CRN" }
      ],
      "taxSchemes": [
        { "companyId": "310122393500003", "taxScheme": { "id": "VAT" } }
      ],
      "postalAddress": {
        "streetName": { "en": "123 King Fahd Rd", "ar": "١٢٣ طريق الملك فهد" },
        "buildingNumber": "1234",
        "cityName": { "en": "Riyadh", "ar": "الرياض" },
        "district": { "en": "Olaya", "ar": "العليا" },
        "postalZone": "11564",
        "country": { "identificationCode": "SA" }
      }
    },
    "buyer": {
      "name": { "en": "Global Imports Inc.", "ar": "شركة الاستيراد العالمية" },
      "identifications": [
        { "id": "310122393500004", "schemeId": "CRN" }
      ],
      "taxSchemes": [
        { "companyId": "310122393500004", "taxScheme": { "id": "VAT" } }
      ],
      "postalAddress": {
        "streetName": { "en": "456 Olaya St", "ar": "٤٥٦ شارع العليا" },
        "buildingNumber": "5678",
        "cityName": { "en": "Jeddah", "ar": "جدة" },
        "district": { "en": "Al Hamra", "ar": "الحمرا" },
        "postalZone": "22233",
        "country": { "identificationCode": "SA" }
      }
    }
  },
  "items": [
    {
      "id": "1",
      "description": { "en": "Premium Widget", "ar": "أداة مميزة" },
      "quantity": 5,
      "unitCode": "PCS",
      "unitPrice": 100.00,
      "taxTotal": { "taxAmount": 75.00 },
      "item": {
        "name": { "en": "Premium Widget", "ar": "أداة مميزة" },
        "classifiedTaxCategory": {
          "id": "S",
          "percent": 15,
          "taxScheme": { "id": "VAT" },
          "taxExemptionReasonCode": "E1",
          "taxExemptionReason": "Export of goods"
        }
      },
      "discountPerUnit": 5.00,
      "lineExtensionAmount": 500.00,
      "netLineExtensionAmount": 475.00
    }
  ],
  "taxTotals": [
    {
      "taxAmount": 75.00,
      "taxSubtotal": [
        {
          "taxableAmount": 500.00,
          "taxAmount": 75.00,
          "taxCategory": {
            "id": "S",
            "percent": 15,
            "taxScheme": { "id": "VAT" }
          }
        }
      ]
    }
  ],
  "legalMonetaryTotal": {
    "lineExtensionAmount": 500.00,
    "taxExclusiveAmount": 500.00,
    "taxInclusiveAmount": 575.00,
    "payableAmount": 575.00,
    "vatTotalAmount": 75.00
  },
  "meta": {
    "customFields": {
      "sa_isSimplifiedInvoice": false
    }
  }
}

B2C Simplified Tax Invoice

Retail - Business-to-consumer simplified tax invoice for retail transactions, using canonical GETS structure.

{
  "header": {
    "invoiceId": "INV-2024-002",
    "issueDate": "2024-06-01",
    "issueTime": "11:00:00Z",
    "documentCurrency": "SAR",
    "documentType": "simplified_tax_invoice"
  },
  "parties": {
    "seller": {
      "name": { "en": "Acme Trading LLC", "ar": "شركة اكمي للتجارة" },
      "identifications": [
        { "id": "310122393500003", "schemeId": "CRN" }
      ],
      "taxSchemes": [
        { "companyId": "310122393500003", "taxScheme": { "id": "VAT" } }
      ],
      "postalAddress": {
        "streetName": { "en": "123 King Fahd Rd", "ar": "١٢٣ طريق الملك فهد" },
        "buildingNumber": "1234",
        "cityName": { "en": "Riyadh", "ar": "الرياض" },
        "district": { "en": "Olaya", "ar": "العليا" },
        "postalZone": "11564",
        "country": { "identificationCode": "SA" }
      }
    },
    "buyer": {
      "name": { "en": "Retail Customer", "ar": "عميل التجزئة" },
      "postalAddress": {
        "streetName": { "en": "Walk-in", "ar": "حضور شخصي" }
      }
    }
  },
  "items": [
    {
      "id": "1",
      "description": { "en": "Standard Service", "ar": "خدمة قياسية" },
      "quantity": 1,
      "unitCode": "PCS",
      "unitPrice": 200.00,
      "taxTotal": { "taxAmount": 30.00 },
      "item": {
        "name": { "en": "Standard Service", "ar": "خدمة قياسية" },
        "classifiedTaxCategory": {
          "id": "S",
          "percent": 15,
          "taxScheme": { "id": "VAT" }
        }
      }
    }
  ],
  "taxTotals": [
    {
      "taxAmount": 30.00,
      "taxSubtotal": [
        {
          "taxableAmount": 200.00,
          "taxAmount": 30.00,
          "taxCategory": {
            "id": "S",
            "percent": 15,
            "taxScheme": { "id": "VAT" }
          }
        }
      ]
    }
  ],
  "legalMonetaryTotal": {
    "lineExtensionAmount": 200.00,
    "taxExclusiveAmount": 200.00,
    "taxInclusiveAmount": 230.00,
    "payableAmount": 230.00,
    "vatTotalAmount": 30.00
  },
  "meta": {
    "customFields": {
      "sa_isSimplifiedInvoice": true
    }
  }
}

B2B Credit Note

Adjustment - Business-to-business credit note for adjustments and returns with full GETS structure.

{
  "header": {
    "invoiceId": "CN-2024-001",
    "issueDate": "2024-06-02",
    "issueTime": "14:00:00Z",
    "documentCurrency": "SAR",
    "documentType": "credit_note",
    "billingReference": {
      "invoiceDocumentReference": {
        "id": "INV-2024-001",
        "issueDate": "2024-06-01"
      }
    }
  },
  "parties": {
    "seller": {
      "name": { "en": "Acme Trading LLC", "ar": "شركة اكمي للتجارة" },
      "identifications": [
        { "id": "310122393500003", "schemeId": "CRN" }
      ],
      "taxSchemes": [
        { "companyId": "310122393500003", "taxScheme": { "id": "VAT" } }
      ]
    },
    "buyer": {
      "name": { "en": "Global Imports Inc.", "ar": "شركة الاستيراد العالمية" },
      "identifications": [
        { "id": "310122393500004", "schemeId": "CRN" }
      ]
    }
  },
  "items": [
    {
      "id": "1",
      "description": { "en": "Returned Widget", "ar": "أداة مُرتجعة" },
      "quantity": -1,
      "unitCode": "PCS",
      "unitPrice": 100.00,
      "taxTotal": { "taxAmount": -15.00 },
      "item": {
        "name": { "en": "Returned Widget", "ar": "أداة مُرتجعة" },
        "classifiedTaxCategory": {
          "id": "S",
          "percent": 15,
          "taxScheme": { "id": "VAT" }
        }
      },
      "lineExtensionAmount": -100.00
    }
  ],
  "taxTotals": [
    {
      "taxAmount": -15.00,
      "taxSubtotal": [
        {
          "taxableAmount": -100.00,
          "taxAmount": -15.00,
          "taxCategory": {
            "id": "S",
            "percent": 15,
            "taxScheme": { "id": "VAT" }
          }
        }
      ]
    }
  ],
  "legalMonetaryTotal": {
    "lineExtensionAmount": -100.00,
    "taxExclusiveAmount": -100.00,
    "taxInclusiveAmount": -115.00,
    "payableAmount": -115.00,
    "vatTotalAmount": -15.00
  }
}

B2B Prepayment Invoice

Advanced - Business prepayment invoice with advance payment handling and GETS compliance.

{
  "header": {
    "invoiceId": "PP-2024-001",
    "issueDate": "2024-06-01",
    "issueTime": "08:00:00Z",
    "documentCurrency": "SAR",
    "documentType": "prepayment_invoice"
  },
  "parties": {
    "seller": {
      "name": { "en": "Acme Trading LLC", "ar": "شركة اكمي للتجارة" },
      "identifications": [
        { "id": "310122393500003", "schemeId": "CRN" }
      ],
      "taxSchemes": [
        { "companyId": "310122393500003", "taxScheme": { "id": "VAT" } }
      ]
    },
    "buyer": {
      "name": { "en": "Global Imports Inc.", "ar": "شركة الاستيراد العالمية" },
      "identifications": [
        { "id": "310122393500004", "schemeId": "CRN" }
      ]
    }
  },
  "items": [
    {
      "id": "1",
      "description": { "en": "Prepayment for Services", "ar": "دفعة مقدمة للخدمات" },
      "quantity": 1,
      "unitCode": "PCS",
      "unitPrice": 1000.00,
      "taxTotal": { "taxAmount": 150.00 },
      "item": {
        "name": { "en": "Prepayment for Services", "ar": "دفعة مقدمة للخدمات" },
        "classifiedTaxCategory": {
          "id": "S",
          "percent": 15,
          "taxScheme": { "id": "VAT" }
        }
      },
      "lineExtensionAmount": 1000.00
    }
  ],
  "taxTotals": [
    {
      "taxAmount": 150.00,
      "taxSubtotal": [
        {
          "taxableAmount": 1000.00,
          "taxAmount": 150.00,
          "taxCategory": {
            "id": "S",
            "percent": 15,
            "taxScheme": { "id": "VAT" }
          }
        }
      ]
    }
  ],
  "legalMonetaryTotal": {
    "lineExtensionAmount": 1000.00,
    "taxExclusiveAmount": 1000.00,
    "taxInclusiveAmount": 1150.00,
    "payableAmount": 1150.00,
    "vatTotalAmount": 150.00,
    "prepaidAmount": 1150.00
  },
  "paymentMeans": [
    {
      "paymentMeansCode": "10",
      "paymentDueDate": "2024-06-01"
    }
  ]
}

Java SDK Payload Examples

Real payload structures from LogicalDocumentTypeFlowSample.java that work with the current Java SDK

B2B Payload

Java Map structure for B2B Tax Invoice using LogicalDocType.TAX_INVOICE

Map<String, Object> payload = new HashMap<>();

// Invoice Data - Maps to GETS header fields
Map<String, Object> invoiceData = new HashMap<>();
invoiceData.put("invoice_number", "RETRTTESTNEW1124");
invoiceData.put("invoice_date", "2025-09-04");
invoiceData.put("invoice_time", "14:30:00");
invoiceData.put("currency_code", "SAR");
invoiceData.put("total_amount", 23000.00);
invoiceData.put("total_payable_amount", 23000.00);
invoiceData.put("tax_exclusive_amount", 20000.00);
invoiceData.put("line_extension_amount", 20000.00);
invoiceData.put("total_tax_amount", 3000.00);
payload.put("invoice_data", invoiceData);

// Seller Info - Maps to GETS seller party fields
Map<String, Object> sellerInfo = new HashMap<>();
sellerInfo.put("company_name", "Advanced Tech Solutions LLC");
sellerInfo.put("vat_registration", "310123456700003");
sellerInfo.put("tax_scheme", "VAT");
sellerInfo.put("street_address", "King Fahd Road");
sellerInfo.put("building_number", "1234");
sellerInfo.put("district_name", "Al Olaya");
sellerInfo.put("city_name", "Riyadh");
sellerInfo.put("postal_code", "11564");
sellerInfo.put("country_code", "SA");
sellerInfo.put("phone", "+966501234567");
sellerInfo.put("email", "contact@advancedtech.sa");
payload.put("seller_info", sellerInfo);

// Buyer Info - Maps to GETS buyer party fields
Map<String, Object> buyerInfo = new HashMap<>();
buyerInfo.put("buyer_name", "Global Manufacturing Co.");
buyerInfo.put("buyer_vat", "310987654300003");
buyerInfo.put("buyer_address", "Industrial City");
buyerInfo.put("buyer_building", "4567");
buyerInfo.put("buyer_district", "Industrial Area");
buyerInfo.put("buyer_city", "Dammam");
buyerInfo.put("buyer_postal", "31461");
buyerInfo.put("buyer_country", "SA");
payload.put("buyer_info", buyerInfo);

B2C Payload

Java Map structure for B2C Simplified Invoice using LogicalDocType.SIMPLIFIED_TAX_INVOICE

// B2C Simplified Invoice - automatically sets isB2B=false
Map<String, Object> payload = new HashMap<>();

// Invoice Data
Map<String, Object> invoiceData = new HashMap<>();
invoiceData.put("invoice_number", "STI-2024-001234");
invoiceData.put("invoice_date", "2025-09-04");
invoiceData.put("currency_code", "SAR");
invoiceData.put("total_amount", 1150.00);
invoiceData.put("tax_exclusive_amount", 1000.00);
invoiceData.put("total_tax_amount", 150.00);
payload.put("invoice_data", invoiceData);

// Seller Info (required for B2C)
Map<String, Object> sellerInfo = new HashMap<>();
sellerInfo.put("company_name", "Retail Store LLC");
sellerInfo.put("vat_registration", "310123456700003");
sellerInfo.put("street_address", "Main Street Shop");
sellerInfo.put("city_name", "Riyadh");
sellerInfo.put("country_code", "SA");
payload.put("seller_info", sellerInfo);

// Buyer Info (minimal for B2C)
Map<String, Object> buyerInfo = new HashMap<>();
buyerInfo.put("buyer_name", "Walk-in Customer");
buyerInfo.put("buyer_country", "SA");
payload.put("buyer_info", buyerInfo);

// Line Items
List<Map<String, Object>> lineItems = new ArrayList<>();
Map<String, Object> item1 = new HashMap<>();
item1.put("item_id", "RETAIL001");
item1.put("item_name", "Consumer Product");
item1.put("quantity", "1");
item1.put("unit_price", "1000.00");
item1.put("tax_amount", "150.00");
item1.put("tax_rate", "15");
lineItems.add(item1);
payload.put("line_items", lineItems);

Complete Example

Complete working example from LogicalDocumentTypeFlowSample.java

public class KSAInvoiceExample {
    public static void main(String[] args) {
        try {
            // Configure SDK
            Source source = new Source("example-source", "1.1", SourceType.FIRST_PARTY);
            SDKConfig config = new SDKConfig(
                "ak_5ddc725b240f9fa39a336e65ceb4",
                Environment.SANDBOX,
                Arrays.asList(source)
            );
            GETSUnifySDK.configure(config);

            // Create comprehensive KSA payload
            Map<String, Object> payload = createKSAPayload();

            // Submit B2B Tax Invoice
            UnifyResponse response = GETSUnifySDK.pushToUnify(
                "example-source",                      // Source name
                "1.1",                         // Source version
                LogicalDocType.TAX_INVOICE,    // B2B Tax Invoice
                Country.SA,                    // Saudi Arabia
                Operation.SINGLE,              // Single document
                Mode.DOCUMENTS,                // Document mode
                Purpose.INVOICING,             // Full invoicing flow
                payload                        // Business data
            );

            if ("success".equalsIgnoreCase(response.getStatus())) {
                System.out.println("KSA Invoice submitted successfully!");
                if (response.getData() != null && response.getData().getSubmission() != null) {
                    System.out.println("🆔 Submission ID: " + 
                        response.getData().getSubmission().getSubmissionId());
                }
            }

        } catch (Exception e) {
            System.err.println("❌ KSA Invoice submission failed: " + e.getMessage());
        }
    }

    private static Map<String, Object> createKSAPayload() {
        // Use the complete payload structure from LogicalDocumentTypeFlowSample
        // This includes 37/37 GETS fields and 6/6 SA country fields
        // See the complete implementation in the sample file
        return LogicalDocumentTypeFlowSample.createComprehensiveTestPayload();
    }
}

KSA-Specific Features

Required Fields

Bilingual descriptions (English/Arabic)
Supply start/end dates
VAT total amounts
Document type with calculations
Line extension amounts

ZATCA Compliance

Phase 2 Integration ready
VAT exemption reason codes
Building numbers and postal codes
Switch to Arabic
Cancel/Refund invoices

Implementation Guide

How to use these examples in your application.

1. Choose the Right LogicalDocType

// B2B Tax Invoices
LogicalDocType.TAX_INVOICE                    // Standard B2B invoice
LogicalDocType.TAX_INVOICE_CREDIT_NOTE       // B2B credit note
LogicalDocType.TAX_INVOICE_DEBIT_NOTE        // B2B debit note
LogicalDocType.TAX_INVOICE_PREPAYMENT        // B2B prepayment

// B2C Simplified Invoices
LogicalDocType.SIMPLIFIED_TAX_INVOICE        // B2C simplified invoice
LogicalDocType.SIMPLIFIED_TAX_INVOICE_CREDIT_NOTE  // B2C credit note
LogicalDocType.SIMPLIFIED_TAX_INVOICE_DEBIT_NOTE   // B2C debit note

// Prepayment Invoices
LogicalDocType.TAX_INVOICE_PREPAYMENT        // B2B prepayment
LogicalDocType.SIMPLIFIED_TAX_INVOICE_PREPAYMENT   // B2C prepayment

2. Submit via Java SDK

// Configure SDK
SDKConfig config = new SDKConfig.Builder()
    .apiKey("your-api-key")
    .environment(Environment.SANDBOX)
    .appId("your-app-id")
    .defaultCountry("SA")
    .build();

GETSUnifySDK.configure(config);

// Create payload (use examples above)
Map<String, Object> payload = createKSAPayload();

// Submit to GETS
UnifyResponse response = GETSUnifySDK.pushToUnify(
    "your-source-name",           // Source name
    "1.0",                        // Source version
    LogicalDocType.TAX_INVOICE,   // Document type
    Country.SA,                   // Saudi Arabia
    Operation.SINGLE,             // Single document
    Mode.DOCUMENTS,               // Document mode
    Purpose.INVOICING,            // Full invoicing flow
    payload                       // Business data
);