Generate E-Invoice | ClearTax Docs

Subscribe for Updates

Generate a valid E-Invoice with JSON payload and send it to ZATCA for clearance or reporting.

Request Method

POST

Request URL

{{BASE_URL}}/v2/einvoices/generate

Replace the {{BASE_URL}} with the one mentioned based on whether you are using sandbox or production.

Rate Limit : 1000 API requests per minute

Request Headers

Parameter

Data Type

Field Validations

Description

x-cleartax-auth-token

String

Cannot be empty.

vat

String

Cannot be empty

Mandatory. VAT or Group VAT of the entity.

branch

String

Should be a valid branch from the user account

Optional. Branch name (store name) added in the user account which maps to a VAT or Group VAT of the entity.

accept-language

String

Enum: ar, en

Optional. Language of error message from ZATCA.

ar - Arabic

en - English

Default: en.

Request Path Params

There are no path parameters for this API.

Request Query Params

There are no query parameters for this API.

Request Body

Parameter

Data Type

Field Validation

Description

DeviceId

String

MaxLength: 36

EInvoice

Object

NA

CustomFields

Object

NA

Optional. Custom Fields object

Custom Fields Object

This is a custom object of key-value pairs that can be used to display custom fields in custom output PDF templates or in certain reports. For example:

{
    "country_of_origin": "IN",
    "total_containers": "3"
}

Requirement of Critical Fields

Fields

Generate E-Invoice API (via JSON)

Generate E-Invoice via XML API

UUID

Optional. Will be generated by ClearTax if not sent in input.

Optional. Will be generated by ClearTax if not sent in input.

ICV

Read Only. Will be ignored if sent in input.

Read Only. Will be ignored if sent in input.

PIH

Read Only. Will be ignored if sent in input.

Read Only. Will be ignored if sent in input.

InvoiceHash

Read Only. Will be ignored if sent in input.

Read Only. Will be ignored if sent in input.

Signature

Read Only. Will be ignored if sent in input.

Read Only. Will be ignored if sent in input.

RawQRCode

Read Only. Will be ignored if sent in input.

Read Only. Will be ignored if sent in input.

InvoiceXml

NA. Not available in the input schema.

NA. Not available in the input schema. The XML received will be enhanced before sending to ZATCA.

The use case where generation CSID (at customer side) and reporting CSID (at ClearTax side) is different, is not supported at the moment.

Sample Request

{
    "DeviceId": "{{DeviceId}}",
    "EInvoice": {
        "ProfileID": "reporting:1.0",
        "ID": {
            "en": "Test179",
            "ar": "Test179"
        },
        "InvoiceTypeCode": {
            "name": "0100000",
            "value": "388"
        },
        "IssueDate": "2023-10-27",
        "IssueTime": "12:15:48",
        "Delivery": [
            {
                "ActualDeliveryDate": "2023-10-27",
                "LatestDeliveryDate": "2023-10-27"
            }
        ],
        "BillingReference": [
            {
                "InvoiceDocumentReference": {
                    "ID": {
                        "ar": null,
                        "en": "156166151"
                    }
                }
            }
        ],
        "OrderReference": {
            "ID": {
                "ar": null,
                "en": "161313031"
            }
        },
        "ContractDocumentReference": [
            {
                "ID": {
                    "ar": null,
                    "en": "1771313066"
                }
            }
        ],
        "DocumentCurrencyCode": "USD",
        "TaxCurrencyCode": "SAR",
        "AccountingSupplierParty": {
            "Party": {
                "PartyLegalEntity": {
                    "RegistrationName": {
                        "en": "ClearTax LCC",
                        "ar": "كليرتاكس ذ.م.م"
                    }
                },
                "PartyTaxScheme": {
                    "CompanyID": "{{vat}}",
                    "TaxScheme": {
                        "ID": "VAT"
                    }
                },
                "PartyIdentification": {
                    "ID": {
                        "schemeID": "CRN",
                        "value": "1010182239"
                    }
                },
                "PostalAddress": {
                    "StreetName": {
                        "en": "AlAlmin Street",
                        "ar": "شارع العلمين"
                    },
                    "AdditionalStreetName": {
                        "en": null,
                        "ar": null
                    },
                    "BuildingNumber": {
                        "en": "6623",
                        "ar": "6623"
                    },
                    "PlotIdentification": {
                        "en": "2892",
                        "ar": "2892"
                    },
                    "CityName": {
                        "en": "Riyadh",
                        "ar": "الرياض"
                    },
                    "CitySubdivisionName": {
                        "en": "Al Shohda Dist.",
                        "ar": "حي الشهداء"
                    },
                    "PostalZone": "13241",
                    "CountrySubentity": {
                        "en": "Riyadh Region",
                        "ar": "منطقة الرياض"
                    },
                    "Country": {
                        "IdentificationCode": "SA"
                    }
                }
            }
        },
        "AccountingCustomerParty": {
            "Party": {
                "PartyLegalEntity": {
                    "RegistrationName": {
                        "en": "ALMARAI COMPANY",
                        "ar": " شركة المراعي"
                    }
                },
                "PartyTaxScheme": {
                    "CompanyID": "{{buyervat}}",
                    "TaxScheme": {
                        "ID": "VAT"
                    }
                },
                "PartyIdentification": null,
                "PostalAddress": {
                    "StreetName": {
                        "en": "STREET NAME EN:Riyadh1",
                        "ar": "أسم الش"
                    },
                    "AdditionalStreetName": null,
                    "BuildingNumber": {
                        "en": "1212",
                        "ar": "1212"
                    },
                    "PlotIdentification": {
                        "en": "1210",
                        "ar": "1210"
                    },
                    "CityName": {
                        "en": "CITY NAME EN",
                        "ar": "أسم المدينة"
                    },
                    "CitySubdivisionName": {
                        "en": "CITY S.DIVISION EN ",
                        "ar": "المدينة - قطاع  "
                    },
                    "PostalZone": "12345",
                    "CountrySubentity": {
                        "en": "COUNTRY EN",
                        "ar": "COUNTRY EN"
                    },
                    "Country": {
                        "IdentificationCode": "SA"
                    }
                }
            }
        },
        "InvoiceLine": [
            {
                "ID": "1",
                "Item": {
                    "Name": {
                        "en": "Item A",
                        "ar": "البند أ"
                    },
                    "BuyersItemIdentification": {
                        "ID": {
                            "en": "PRD789",
                            "ar": null
                        }
                    },
                    "SellersItemIdentification": {
                        "ID": {
                            "en": "ITM123",
                            "ar": null
                        }
                    },
                    "StandardItemIdentification": {
                        "ID": {
                            "en": "9067845",
                            "ar": null
                        }
                    },
                    "ClassifiedTaxCategory": {
                        "ID": "S",
                        "Percent": "15.00",
                        "TaxScheme": {
                            "ID": "VAT"
                        }
                    }
                },
                "Price": {
                    "AllowanceCharge": {
                        "ChargeIndicator": "false",
                        "BaseAmount": {
                            "currencyID": "USD",
                            "value": "55.00"
                        },
                        "Amount": {
                            "currencyID": "USD",
                            "value": "5"
                        }
                    },
                    "PriceAmount": {
                        "currencyID": "USD",
                        "value": "50.00"
                    },
                    "BaseQuantity": {
                        "unitCode": "HMO",
                        "value": "1"
                    }
                },
                "InvoicedQuantity": {
                    "unitCode": "HMO",
                    "value": "10"
                },
                "AllowanceCharge": [
                    {
                        "ChargeIndicator": "false",
                        "BaseAmount": {
                            "currencyID": "USD",
                            "value": "500"
                        },
                        "MultiplierFactorNumeric": "20",
                        "Amount": {
                            "currencyID": "USD",
                            "value": "100"
                        },
                        "AllowanceChargeReason": {
                            "ar": "خصم",
                            "en": "Discount"
                        },
                        "AllowanceChargeReasonCode": null
                    }
                ],
                "LineExtensionAmount": {
                    "currencyID": "USD",
                    "value": "400.00"
                },
                "TaxTotal": {
                    "TaxAmount": {
                        "currencyID": "USD",
                        "value": "60.00"
                    },
                    "RoundingAmount": {
                        "currencyID": "USD",
                        "value": "460.00"
                    }
                }
            },
            {
                "ID": "2",
                "Item": {
                    "Name": {
                        "en": "Item B",
                        "ar": "البند ب"
                    },
                    "ClassifiedTaxCategory": {
                        "ID": "S",
                        "Percent": "15.00",
                        "TaxScheme": {
                            "ID": "VAT"
                        }
                    }
                },
                "Price": {
                    "PriceAmount": {
                        "currencyID": "USD",
                        "value": "300.00"
                    }
                },
                "InvoicedQuantity": {
                    "value": "2"
                },
                "LineExtensionAmount": {
                    "currencyID": "USD",
                    "value": "600.00"
                },
                "TaxTotal": {
                    "TaxAmount": {
                        "currencyID": "USD",
                        "value": "90.00"
                    },
                    "RoundingAmount": {
                        "currencyID": "USD",
                        "value": "690.00"
                    }
                }
            },
            {
                "ID": "3",
                "Item": {
                    "Name": {
                        "en": "Item C",
                        "ar": "البند ج"
                    },
                    "ClassifiedTaxCategory": {
                        "ID": "Z",
                        "Percent": "0.00",
                        "TaxScheme": {
                            "ID": "VAT"
                        }
                    }
                },
                "Price": {
                    "PriceAmount": {
                        "currencyID": "USD",
                        "value": "50.00"
                    }
                },
                "InvoicedQuantity": {
                    "value": "2"
                },
                "LineExtensionAmount": {
                    "currencyID": "USD",
                    "value": "100.00"
                },
                "TaxTotal": {
                    "TaxAmount": {
                        "currencyID": "USD",
                        "value": "0.00"
                    },
                    "RoundingAmount": {
                        "currencyID": "USD",
                        "value": "100.00"
                    }
                }
            },
            {
                "ID": "4",
                "Item": {
                    "Name": {
                        "en": "Prepayment adjustment",
                        "ar": "تعديل الدفع المسبق"
                    },
                    "ClassifiedTaxCategory": {
                        "ID": "S",
                        "Percent": "15.00",
                        "TaxScheme": {
                            "ID": "VAT"
                        }
                    }
                },
                "Price": {
                    "PriceAmount": {
                        "currencyID": "USD",
                        "value": "0.00"
                    }
                },
                "DocumentReference": {
                    "ID": "Advance-test100",
                    "UUID": "5a8a6b8c-2712-4032-9c3a-5e1bc7243e7d",
                    "IssueDate": "2023-08-01",
                    "IssueTime": "12:15:48",
                    "InvoiceTypeCode": "386"
                },
                "InvoicedQuantity": {
                    "unitCode": "EA",
                    "value": "0.00"
                },
                "LineExtensionAmount": {
                    "currencyID": "USD",
                    "value": "0.00"
                },
                "TaxTotal": {
                    "TaxAmount": {
                        "value": "0.00",
                        "currencyID": "USD"
                    },
                    "RoundingAmount": {
                        "currencyID": "USD",
                        "value": "0.00"
                    },
                    "TaxSubtotal": [
                        {
                            "TaxableAmount": {
                                "value": "86.96",
                                "currencyID": "USD"
                            },
                            "TaxAmount": {
                                "value": "13.04",
                                "currencyID": "USD"
                            },
                            "TaxCategory": {
                                "ID": "S",
                                "Percent": "15.00",
                                "TaxScheme": {
                                    "ID": "VAT"
                                },
                                "TaxExemptionReasonCode": "",
                                "TaxExemptionReason": {
                                    "ar": "",
                                    "en": ""
                                }
                            }
                        }
                    ]
                }
            }
        ],
        "AllowanceCharge": [
            {
                "ChargeIndicator": "false",
                "BaseAmount": {
                    "currencyID": "USD",
                    "value": "1000"
                },
                "MultiplierFactorNumeric": "10",
                "Amount": {
                    "currencyID": "USD",
                    "value": "100"
                },
                "TaxCategory": {
                    "ID": "S",
                    "Percent": "15",
                    "TaxScheme": {
                        "ID": "VAT"
                    }
                }
            }
        ],
        "TaxTotal": [
            {
                "TaxAmount": {
                    "currencyID": "SAR",
                    "value": "25.01"
                }
            },
            {
                "TaxAmount": {
                    "currencyID": "USD",
                    "value": "135.00"
                },
                "TaxSubtotal": [
                    {
                        "TaxableAmount": {
                            "currencyID": "USD",
                            "value": "900.00"
                        },
                        "TaxAmount": {
                            "currencyID": "USD",
                            "value": "135.00"
                        },
                        "TaxCategory": {
                            "ID": "S",
                            "Percent": "15.00",
                            "TaxScheme": {
                                "ID": "VAT"
                            }
                        }
                    },
                    {
                        "TaxableAmount": {
                            "currencyID": "USD",
                            "value": "100.00"
                        },
                        "TaxAmount": {
                            "currencyID": "USD",
                            "value": "0"
                        },
                        "TaxCategory": {
                            "ID": "Z",
                            "Percent": "0.00",
                            "TaxScheme": {
                                "ID": "VAT"
                            },
                            "TaxExemptionReasonCode": "VATEX-SA-34-4",
                            "TaxExemptionReason": {
                                "en": "Supply of a qualifying means of transport.",
                                "ar": null
                            }
                        }
                    }
                ]
            }
        ],
        "LegalMonetaryTotal": {
            "LineExtensionAmount": {
                "currencyID": "USD",
                "value": "1100"
            },
            "AllowanceTotalAmount": {
                "currencyID": "USD",
                "value": "100"
            },
            "TaxExclusiveAmount": {
                "currencyID": "USD",
                "value": "1000.00"
            },
            "TaxInclusiveAmount": {
                "currencyID": "USD",
                "value": "1135.00"
            },
            "PrepaidAmount": {
                "currencyID": "USD",
                "value": "100.00"
            },
            "PaybleRoundingAmount": {
                "currencyID": "USD",
                "value": "0"
            },
            "PayableAmount": {
                "currencyID": "USD",
                "value": "1035.00"
            }
        },
        "PaymentMeans": [
            {
                "PaymentMeansCode": 10,
                "InstructionNote": {
                    "en": "",
                    "ar": ""
                },
                "PayeeFinancialAccount": {
                    "PaymentNote": {
                        "en": "",
                        "ar": ""
                    }
                }
            }
        ],
        "Note": {
            "en": "This is a computer generated invoice.",
            "ar": null
        }
    }
}

Additional E-Invoice examples:

Standard (B2B)

Simplified (B2C)

Response Status Codes

HTTP Status Code

Description

200

For a successfully reported or cleared document.

400

For any kind of validation issues either from ClearTax or ZATCA.

401

If the user is not authenticated for the operation.

403

If the user is not authorized for the operation.

429

Too many requests

Response Schema

Parameter

Data Type

Field Validations

Description

DeviceId

String

MaxLength: 36

Optional. Device ID registered in ClearTax.

Status

String

Enum: GENERATED, NOT_GENERATED, GENERATION_FAILED

Mandatory. Status of E-Invoice QR Code Generation and acceptance by ZATCA. Explained below.

QrCodeStatus

String

Enum: GENERATED, NOT_GENERATED, GENERATION_FAILED

Mandatory. Status of E-Invoice QR Code.

GENERATED, NOT_GENERATED, GENERATION_FAILED

InvoiceStatus

String

Enum

NOT_SUBMITTED, FAILED. NOT_REPORTED, REPORTED, CLEARED, NOT_CLEARED. ACCEPTED_WITH_WARNING,

PENDING

Mandatory. Status of submission to ZATCA.

NOT_SUBMITTED, FAILED NOT_REPORTED, REPORTED, CLEARED, NOT_CLEARED ACCEPTED_WITH_WARNING,

PENDING

QRCode

String

NA

Optional. Rendered QR Code image in base64encoded PNG format.

If clearance fails, this will be null.

RawQRCode

String

NA

Optional. QR Code payload in base64encoded TLV format.

For reporting, this will be generated by ClearTax, if not received in the input.

For clearance, this will be generated by ZATCA. If clearance fails, this will be null.

InvoiceXml

String

NA

Optional. In case of Standard invoices, XML returned by ZATCA.

In case of Simplified invoices, XML used for reporting.

UUID

String

NA

Optional. UUID sent to ZATCA

ClearTax generates this before sending to ZATCA, if not sent in input.

ICV

String

NA

Optional. Invoice counter value sent to ZATCA

ClearTax generates this before sending to ZATCA.

PIH

String

NA

Optional. Previous hash value, Invoice hash value of previous invoice reported/cleared for same deviceId

InvoiceHash

String

NA

Optional. Invoice hash value,

Hash value of current invoice xml by removing tags ext:UBLExtensions, cac:AdditionalDocumentReference:QRCode

InvoiceType

String

Enum: INV, CRN, DBN, RECEIPT

Mandatory. Document Type. INV - Invoice, CRN - Credit Note, DBN - Debit Note, RECEIPT - Receipt.

InvoiceNumber

String

Cannot be null.

Mandatory. Invoice number (ID) as per the input.

IssueDate

String

Cannot be null.

Mandatory. Issue Date as per the input.

IssueTime

String

Format: HH:mm:ss (24 hr format)

Mandatory. Invoice issue time. The time when the invoice was issued.

GeneratedDate

String

Cannot be null.

Mandatory. Date on which the invoice was generated.

GeneratedTime

String

Format: HH:mm:ss (24 hr format)

Mandatory. Invoice generation time. The time when the invoice was generated.

SellerVatNumber

String

Cannot be null.

Mandatory. Seller VAT identification number.

BuyerVatNumber

String

Cannot be null.

Optional. Buyer VAT identification number.

ErrorList

Array

NA

WarningList

Array

NA

Message

String

NA

Optional. Message received from ZATCA.

Explanation of QrCodeStatus

ClearTax generated ICV, IH, PIH, etc

Transmission from ClearTax to ZATCA

ZATCA accepted (cleared or reported)

QrCodeStatus for Standard

QrCodeStatus for Simplified

SUCCESS

SUCCESS

SUCCESS

GENERATED

GENERATED

SUCCESS

SUCCESS

FAILED

GENERATION_FAILED

GENERATED

SUCCESS

FAILED

NA

GENERATION_FAILED

GENERATED

FAILED

NA

NA

GENERATION_FAILED

GENERATION_FAILED

NA

NA

NA

NOT_GENERATED

NOT_GENERATED

If QrCodeStatus is GENERATED, then the invoice can be issued.

Explanation of InvoiceStatus

ClearTax generated ICV, IH, PIH, etc

Transmission with ZATCA

ZATCA accepted (cleared or reported)

InvoiceStatus for Standard

InvoiceStatus for Simplified

SUCCESS

SUCCESS

SUCCESS

CLEARED

REPORTED / ACCEPTED_WITH_WARNING

SUCCESS

SUCCESS

FAILED

NOT_CLEARED

NOT_REPORTED

SUCCESS

SUCCESS

FAILED

FAILED

FAILED

SUCCESS

FAILED

NA

PENDING

PENDING

FAILED

NA

NA

FAILED

FAILED

NA

NA

NA

NOT_SUBMITTED

NOT_SUBMITTED

If InvoiceStatus is CLEARED or REPORTED or ACCEPTEDWITHWARNING, then no further action is required. NOT_SUBMITTED may be returned only in the case of Excel upload on the Web UI. Else, an invoice with valid data needs to be sent to ClearTax.

Sample Response

Success for Simplified Document - HTTP Status Code - 200

{
    "DeviceId": "625410e387173015f7e5a4c6",
    "Status": "GENERATED",
    "QrCodeStatus": "GENERATED",
    "InvoiceStatus": "REPORTED",
    "QRCode": "MjAsSIy1….",
    "RawQRCode": "ARlBb….",
    "InvoiceXml": "ASsdfkf...",
    "UUID": "03779160-c140-4a32-9f9a-7b429149c0ef",
    "ICV": "61",
    "PIH": "KILyvZqPxblzStkif5UsaEtMhLDZUgU/VudKsBFxQN0=",
    "InvoiceHash": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
    "InvoiceType": "INV",
    "InvoiceNumber": "315",
    "IssueDate": "2021-04-25",
    "IssueTime": "16:42:25",
    "GeneratedDate": "2021-04-25",
    "GeneratedTime": "16:42:25",
    "SellerVatNumber": "300492946900003",
    "BuyerVatNumber": null,
    "ErrorList": [],
    "WarningList":[],
    "Message": null
}

Success for Standard Document - HTTP Status Code - 200

{
    "DeviceId": "625410e387173015f7e5a4c6",
    "Status": "GENERATED",
    "QrCodeStatus": "GENERATED",
    "InvoiceStatus": "CLEARED",
    "QRCode": "iBU5ul8ZaHcbmWYy3zL.....",
    "RawQRCode": "ARlBbCBTYWxhbSBTdXB.......",
    "InvoiceXml": "PD94PC....",
    "UUID": "ed7d6a63-e650-425d-b1eb-f54187a0ccca",
    "ICV": "62",
    "PIH": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
    "InvoiceHash": "u+zU7f/JDKpjoKrNUMF5Z3Kho3cqb1VUoNSCIphyZu8=",
    "InvoiceType": "INV",
    "InvoiceNumber": "130",
    "IssueDate": "2021-04-25",
    "IssueTime": "16:42:25",
    "GeneratedDate": "2021-04-25",
    "GeneratedTime": "16:42:25",
    "SellerVatNumber": "300492946900003",
    "BuyerVatNumber": null,
    "ErrorList":[],
    "WarningList": [],
    "Message": null
}

Success with Warning - HTTP Status Code - 200

{
    "DeviceId": "625410e387173015f7e5a4c6",
    "Status": "GENERATED",
    "QrCodeStatus": "GENERATED",
    "InvoiceStatus": "ACCEPTED_WITH_WARNING",
    "QRCode": "i+GdAUnzMJS.....",
    "RawQRCode": "ARlBbCBTYWxhbSBTdXBwbGllcyBDby4g.....",
    "InvoiceXml": "ASsdfkf...",
    "UUID": "03779160-c140-4a32-9f9a-7b429149c0ef",
    "ICV": "61",
    "PIH": "KILyvZqPxblzStkif5UsaEtMhLDZUgU/VudKsBFxQN0=",
    "InvoiceHash": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
    "InvoiceType": "INV",
    "InvoiceNumber": "315",
    "IssueDate": "2021-04-25",
    "IssueTime": "16:42:25",
    "GeneratedDate": "2021-04-25",
    "GeneratedTime": "16:42:25",
    "SellerVatNumber": "300492946900003",
    "BuyerVatNumber": null,
    "ErrorList": [],
    "WarningList": [
        {
            "ErrorCode": "BR-KSA-09",
            "ErrorMessage": "Seller address must contain additional number (KSA-23), street name (BT-35), building number (KSA-17), postal code (BT-38), city (BT-37), Neighborhood (KSA-3), country code (BT-40). \n  For more information please access this link: https://www.address.gov.sa/en/address-format/overview",
            "ErrorSource": "ZATCA"
        }
    ],
   "Message": null
}

Error from ClearTax - HTTP Status Code - 400

{
    "InvoiceType": "INV",
    "InvoiceNumber": "2022",
    "IssueDate": "2021-04-25",
    "IssueTime": "16:42:25",
    "SellerVatNumber": "300492946900003",
    "Status": "GENERATION_FAILED",
    "QrCodeStatus": "GENERATION_FAILED",
    "InvoiceStatus": "FAILED",
    "ErrorList": [
        {
            "ErrorCode": "6002",
            "ErrorMessage": "If Supplier Group Vat number is provided, scheme id must be HQ",
            "ErrorSource": "CLEARTAX",
            "Path": "EInvoice.AccountingSupplierParty.Party.PartyIdentification.ID.schemeID"
        },
        {
            "ErrorCode": "6002",
            "ErrorMessage": "Payment means code in an invoice must contain one of the values (10, 30, 42, 48, 1). In the simplified tax invoice and associated credit notes and debit notes this value is optional.",
            "ErrorSource": "CLEARTAX",
            "Path": "EInvoice.PaymentMeans.PaymentMeansCode"
        }
    ],
}

Error from ZATCA - HTTP Status Code - 200 (Sample Simplified invoice where QR code is generated by ClearTax and then sent to ZATCA for reporting which is not approved by ZATCA).

Note: In case a document is validated by ClearTax but failed at ZATCA, then the HTTP Status Code will be 200 and not 400.

{
    "DeviceId": "625410e387173015f7e5a4c6",
    "Status": "GENERATED",
    "QrCodeStatus": "GENERATED",
    "InvoiceStatus": "NOT_REPORTED",
    "QRCode": "i+GdAUnzMJS.....",
    "RawQRCode": "ARlBbCBTYWxhbSBTdXBwbGllcyBDby4g.....",
    "InvoiceXml": null,
    "UUID": "03779160-c140-4a32-9f9a-7b429149c0ef",
    "ICV": "61",
    "PIH": "KILyvZqPxblzStkif5UsaEtMhLDZUgU/VudKsBFxQN0=",
    "InvoiceHash": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
    "InvoiceType": "INV",
    "InvoiceNumber": "315",
    "IssueDate": "2021-04-25",
    "IssueTime": "16:42:25",
    "SellerVatNumber": "300492946900003",
    "BuyerVatNumber": null,
    "ErrorList": [
        {
            "ErrorCode": "Invalid-Invoice-Hash",
            "ErrorMessage": "The provided invoice hash is invalid",
            "ErrorSource": "ZATCA"
        }
    ],
    "WarningList": [],
    "Message": null
}

Error from ZATCA - Sample Standard invoice with multiple errors which is not approved by Zatca and hence the InvoiceStatus will be "NOT_CLEARED" and QrCodeStatus will be "NOT_GENERATED".

{
    "DeviceId": "09569f97-dd87-4b50-b226-a644b0cb0ab8",
    "Status": "NOT_GENERATED",
    "QrCodeStatus": "NOT_GENERATED",
    "InvoiceStatus": "NOT_CLEARED",
    "QRCode": null,
    "RawQRCode": null,
    "InvoiceXml": null,
    "UUID": "e6791446-844d-4fd1-b4d3-1ae2d111abf8",
    "ICV": "36",
    "PIH": "a+ae0fY+MBboXiFPkZicCIF8ceL2sEnU/fBeQpWEPP4=",
    "InvoiceHash": "+EYiXktJtVeAEqitiJBxNGlO9Hm29/r8l21Z8LGTbCQ=",
    "InvoiceType": "INV",
    "InvoiceNumber": "S-INV-0004",
    "IssueDate": "2021-04-25",
    "IssueTime": "16:42:25",
    "SellerVatNumber": "300492946900003",
    "BuyerVatNumber": "300526201800003",
    "ErrorList": [
        {
            "ErrorCode": "BR-CO-15",
            "ErrorMessage": "Invoice total amount with VAT (BT-112) ",
            "ErrorSource": "ZATCA"
        },
        {
            "ErrorCode": "BR-DEC-20",
            "ErrorMessage": "The allowed maximum number of decimals for the VAT category tax amount (BT-117) is 2.",
            "ErrorSource": "ZATCA"
        },
        {
            "ErrorCode": "BR-DEC-13",
            "ErrorMessage": "The allowed maximum number of decimals for the Invoice total VAT amount (BT-110) is 2.-BR-DEC-15",
            "ErrorSource": "ZATCA"
        },
        {
            "ErrorCode": "BR-DEC-14",
            "ErrorMessage": "The allowed maximum number of decimals for the Invoice total amount with VAT (BT-112) is 2.",
            "ErrorSource": "ZATCA"
        },
        {
            "ErrorCode": "BR-CO-14",
            "ErrorMessage": "Invoice total VAT amount (BT-110) ",
            "ErrorSource": "ZATCA"
        },
        {
            "ErrorCode": "BR-DEC-18",
            "ErrorMessage": "The allowed maximum number of decimals for the Amount due for payment (BT-115) is 2.",
            "ErrorSource": "ZATCA"
        }
    ],
    "WarningList": [],
    "Message": null
}

Error from ZATCA - If we are getting 401 from Zatca, so in that case the Invoice status will be FAILED.

{
    "QRCode": null,
    "RawQRCode": null,
    "UUID": "308a9c99-d727-487e-a327-1d8d84123c09",
    "PIH": "ihAo9IepEZ4Ek4mOR4Kh9ou/hGKuqcBgekj+IdXovm4=",
    "InvoiceHash": "wQ1bduk6PCUiKStxqyrxQHHGs8a9SFVYb3rfaeM7Oxo=",
    "ICV": "31574",
    "DeviceId": "36175d8a-240d-4282-9da3-cfbc1a7a8fa0",
    "SellerVatNumber": "311555804900003",
    "BuyerVatNumber": "300008123400003",
    "Status": "NOT_GENERATED",
    "QrCodeStatus": "NOT_GENERATED",
    "InvoiceStatus": "FAILED",
    "InvoiceType": "INV",
    "InvoiceNumber": "Jitna-02",
    "IssueDate": "2025-03-25",
    "IssueTime": "12:15:48",
    "GeneratedDate": null,
    "GeneratedTime": null,
    "InvoiceXml": null,
    "WarningList": null,
    "ErrorList": [
        {
            "ErrorCode": "401",
            "ErrorMessage": "User is not authorized",
            "ErrorSource": "ZATCA"
        }
    ],
    "Message": null,
    "ValidationsSuccess": true,
    "UniqueId": "311555804900003_Jitna-02_388_2025",
    "UniqueReqIdentifier": null,
    "Id": "67ebc64f40a9a738f9cd5491",
    "TimeDifference": 0,
    "ReportingTime": null,
    "Vat": "311555804900003"
}

API Validations

New validation rules coming soon!

There are a few changes proposed by ZATCA in the revised E-Invoicing Regulation and related guidelines which are currently under public consultation. Once the same is finalized and notified, the validation rules may change.

API Constraints

This API needs to be authenticated with a valid user authentication token. If the auth token is not present or is invalid, the API will return HTTP Status Code 401.
Each customer is allowed to send a limited number of requests per minute to prevent server overload. If the limit is exceeded, the server will respond with a 429 Too Many Requests status code.
If the auth token is valid, but the user does not have the authorization to generate device ID, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an Admin role for the particular VAT used in the request.