Get Bulk Invoice Lite

Get the E-Invoice status and error message details in bulk for invoices using unique identifiers of the invoice.

Request Method

POST

Request URL

{{BASE_URL}}/v3/einvoices/get-bulk

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

Rate Limit : 10 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.

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 Validations	Description
Invoices	List	Maximum invoice list can be up to 500	Mandatory. List of Invoice
methodOfGeneration	String	Enum : ONLINE, OFFLINE	Optional: default is both OFFLINE and ONLINE

Invoices Object

User has to send either UniqueId or the four invoice parameters (Invoice number, Invoice type, Invoice issue date and VAT) to fetch the details.

Parameter	Data Type	Field Validations	Description
uniqueId	String	Should be present if the next 4 parameters are absent	Conditional. Concat of seller vat + invoice id + invoice type code + issue year. All these entities are separated by underscore. Either unique id or invoice details are required to fetch the details.
invoiceNumber	String	NA	Conditional. Document Number (Invoice Reference Number).
invoiceType	String	Enum: INV, CRN, DBN	Conditional. INV - Invoice, CRN - Credit Note, DBN - Debit Note
issueDate	String	yyyy-mm-dd	Conditional. Document Date
vat	String	NA	Conditional. VAT Number.

Sample Request

Request Body

(Without MethodOfGeneration)

{
    "Invoices": [
           {
                "invoiceNumber": "RR-INV-0001",
                "invoiceType": "INV",
                "issueDate": "2022-08-13",
                "vat": "12345678901234"
           },
           {
                "uniqueId": "12345678901234_RR-INV-0002_388_2022"
           },
           {
                "uniqueId": "12345678901234_RR-INV-0013_388_2022"
           }

    ]
}

Request Body

(With MethodOfGeneration)

Method of generation is an optional field but giving this will help in querying and fetching the details of the invoices faster.

{
    "Invoices": [
           {
                "invoiceNumber": "RR-INV-0001",
                "invoiceType": "INV",
                "issueDate": "2022-08-13",
                "vat": "12345678901234"
           },
           {
                "uniqueId": "12345678901234_RR-INV-0002_388_2022"
           },
           {
                "uniqueId": "12345678901234_RR-INV-0013_388_2022"
           }

    ],
   "methodOfGeneration": "ONLINE"
}

Response Status Codes

HTTP Status Code	Description
200	For successful retrieval
401	If the user is not authenticated for the operation
403	If the user is not authorized for the operation
429	Too many requests
5XX	Unhandled exception

Response Schema

Parameter	Data Type	Field Validations	Description
invoiceNumber	String	Cannot be null	Mandatory. Invoice number (ID) as per the input.
einvoiceStatus	Object	PENDING / REPORTED / NOT_REPORTED / ACCEPTED_WITH_WARNING / CLEARED / NOT_CLEARED	For clearance: CLEARED, NOT_CLEARED, ACCEPTED_WITH_WARNING For reported: REPORTED, NOT_REPORTED, ACCEPTED_WITH_WARNING
errorCode	String	Can be empty in case of no error	This field is not empty in case of any error at the time of reporting/clearance. Gives the error code for the error. Error source maybe ClearTax/ZATCA.
errorMessage	String	Can be empty in case of no error	Human readable error message in case of any error at the time of reporting/clearance. Error source maybe ClearTax/ZATCA.

Sample Response (Success)

Success - HTTP Status Code - 200

[
    {
        "invoiceNumber": "INVKSA2218811366",
        "einvoiceStatus": "CLEARED",
        "errorCode": "",
        "errorMessage": ""
    }
]

[
    {
         {
         "invoiceNumber": "13",
         "einvoiceStatus": "NOT_REPORTED"
         "errorCode": "BR-KSA-17, BR-CO-15",
         "errorMessage": "Debit and credit note (invoice type code (BT-3) is equal to 383 or 381) must contain the reason (KSA-10) for this invoice type issuing., Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109) + Invoice total VAT amount (BT-110).",
    }

    }
]

Sample Response (Error)

[
    {
        "invoiceNumber": "RR-INV-0001",
        "einvoiceStatus": "FAILED",
        "errorCode": "300102",
        "errorMessage": "You don't have any data present for the selected Document Details"
    }
]

API Validations

1. The uniqueIdentifier passed in request params should be valid and must be present in ClearTax datastore.

2. Four invoice info fields passed to identify the invoice or the UniqueId passed should belong to the user.

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. The API will accept only 500 invoices in a single request and the API will allow 10 threads running parallel. Hence, data for 5000 invoices can be requested in parallel.

4. The API works for only those invoices present in the CT data store.

5. Plan this API call 1 hour after sending the invoice to ClearTax. If the invoice is still in pending status then plan the subsequent calls 2, 4, 8, 16 and 30 hours. The invoice will have a terminal status as ‘Failed’ max by 30 hours if ZATCA is continuously non-responsive.

6. If the auth token is valid, but the user does not have the authorization to fetch invoice details, 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.