Generate E-Invoice

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 here 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.	Mandatory. User auth token.
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	Mandatory. The Device ID registered with ClearTax. Refer to How to get a Device ID?
EInvoice	Object	NA	Mandatory. E-Invoice object
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)

Additional Standard (B2B) E-Invoice Examples

Simplified (B2C)

Additional Simplified (B2C) E-Invoice Examples

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	Optional. Validation Errors. An array of Error Details Objects. In case there are no errors, this will be an empty Array ([]).
WarningList	Array	NA	Optional. Warnings from ZATCA. An array of Error Details Objects. In case there are no warnings, this will be an empty Array ([]).
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

1. 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.

2. 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.

3. 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.