Upload Invoice to ZATCA
This API receives structured invoice data, validates compliance rules, builds a compliant UBL 2.1 XML document, generates the cryptographic hash & ECDSA digital signature, and automatically submits the invoice to the Saudi Tax Authority (ZATCA) clearance or reporting portal.
HTTP Method
POST
Content-Type
application/json
Standard Supported
ZATCA UBL 2.1
API Endpoint
Full URL example: https://your-domain.com/api/v2/upload-invoice/Reporting/0
Authentication Headers
Requests to this endpoint are protected by the secure.api.password middleware. You must pass your configured secret API password in the Api-Password header.
| Header | Required | Type | Description |
|---|---|---|---|
| Api-Password | YES | string | Matches the server API_PASSWORD setting in .env. |
| Content-Type | YES | string | Must be application/json |
| Accept | RECOMMENDED | string | Must be application/json |
URL Path Parameters
| Parameter | Type | Default | Possible Values | Description |
|---|---|---|---|---|
| {type} | string | Reporting | Reporting | Clearance |
Reporting: Simplified Tax Invoice (B2C, code 0200000). Clearance: Standard Tax Invoice (B2B, code 0100000). |
| {note} | integer | 0 | 0 | 1 |
0: Normal Tax Invoice (Type 388). 1: Credit Note (Type 383) or Debit Note (Type 381). |
JSON Request Body Specification
All fields marked as required must be present in the request body.
1. Seller Information (seller)
| Field | Type | Required | Description & Validation |
|---|---|---|---|
| seller.name | string | YES | Legal registered company name (Arabic or English). |
| seller.commercial_registration_number | string | YES | Commercial Registration (CR) number (e.g. 10 digits). |
| seller.vat_number | string | YES | 15-digit Tax Identification Number (must start and end with '3'). |
| seller.building_number | string | YES | 4-digit National Address building number (e.g. "4222"). |
| seller.street_name | string | YES | Street name. |
| seller.city_subdivision | string | YES | District / Subdivision name. |
| seller.city | string | YES | City name (e.g. "Riyadh"). |
| seller.postal_number | string | YES | 5-digit Saudi Postal Code (e.g. "12345"). |
| seller.plot_identification | string | YES | Additional 4-digit number (e.g. "1234"). |
| seller.country | string | YES | 2-letter ISO Country Code. Must be "SA". |
2. Buyer / Client Information (client)
| Field | Type | Required | Description |
|---|---|---|---|
| client.name | string | YES | Buyer's name or establishment title. |
| client.vat_number | string | B2B ONLY | Buyer's 15-digit VAT number (Mandatory for Standard B2B Clearance). |
| client.commercial_registration_number | string | OPTIONAL | Buyer CR number if available. |
| client.street_name, building_number, city, postal_number | string | B2B ONLY | Buyer's national address details. Mandatory for Standard B2B. |
| client.country | string | YES | 2-letter ISO Country Code (e.g. "SA"). |
3. Invoice Totals & Items
| Field | Type | Required | Description |
|---|---|---|---|
| invoice_number | string | YES | Unique invoice number (e.g. "INV-2026-001"). |
| invoice_date | datetime | YES | ISO date format: "YYYY-MM-DDTHH:MM:SS" (e.g. "2026-10-27T14:30:00"). |
| total_without_vat | numeric | YES | Total taxable amount before VAT and discounts (2 decimals). |
| vat | numeric | YES | Total VAT amount (typically 15% of total_without_vat - discount). |
| discount | numeric | OPTIONAL | Document level discount amount (default 0). |
| invoice_items | array | YES (min 1) | Array of invoice item objects (see below). |
| ↳ name | string | YES | Description of good or service. |
| ↳ quantity | integer | YES | Invoiced quantity (minimum 1). |
| ↳ tax_class_code | string | YES | "S" (Standard 15%), "Z" (Zero-rated), "E" (Exempt), "O" (Out of Scope). |
| ↳ tax_percent | numeric | YES | Tax rate percentage (e.g. 15 for standard rate). |
| ↳ price | numeric | YES | Unit price or line amount before VAT. |
| ↳ vat | numeric | YES | VAT amount for this line (price * 15%). |
| ↳ total | numeric | YES | Line total inclusive of VAT (price + vat). |
4. Additional Fields for Credit / Debit Notes ({note} = 1)
| Field | Type | Required | Description |
|---|---|---|---|
| note_type | string | YES if note=1 | "cn" for Credit Note (383) or "dn" for Debit Note (381). |
| reference_number | string | YES if note=1 | The original invoice number being credited or debited. |
| reason | string | OPTIONAL | Reason for cancellation, return, or price adjustment. |
Code Examples & Payload
Response Payloads
ZATCA Compliance Rules & Best Practices
15% VAT Consistency
Ensure that each line item VAT strictly equals round(price * 15%, 2) and that the sum of line VATs equals the invoice header vat.
15-Digit VAT Number
Saudi VAT numbers must consist of exactly 15 numeric digits, starting with '3' and ending with '3' (e.g. 302008161400003).
UTC / Saudi Timezone Format
invoice_date must be provided in ISO 8601 format (YYYY-MM-DDTHH:MM:SS). Future dates are rejected by ZATCA.
Unit Price vs Line Total
When quantity > 1, our API automatically normalizes whether you pass unit price or line total to avoid taxable amount discrepancies.