Subscribe for Updates

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.

Request Headers

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationDescription

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

FieldsGenerate 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 CodeDescription

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.

Response Schema

ParameterData TypeField ValidationsDescription

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, etcTransmission from ClearTax to ZATCAZATCA accepted (cleared or reported)QrCodeStatus for StandardQrCodeStatus 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, etcTransmission with ZATCAZATCA accepted (cleared or reported)InvoiceStatus for StandardInvoiceStatus for Simplified

SUCCESS

SUCCESS

SUCCESS

CLEARED

REPORTED / ACCEPTED_WITH_WARNING

SUCCESS

SUCCESS

FAILED

NOT_CLEARED

NOT_REPORTED

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",