Cancel E-Invoice

This API allows you to cancel your generated e-invoice within 72 hours from the time of validation. It takes the document id and the reason for cancellation as the input and returns the status of the cancellation activity, with errors if any.

Request Method

PUT

Request URL

{{HOST}}/einvoice/v1/documents/{document_id}/state

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.
x-clear-tin	String	Cannot be empty	Mandatory. TIN of the entity
x-clear-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 TIN of the entity.
x-request-id	UUID	Should be unique for every request	Optional. Unique request ID.
Content-Type	String	application/json	application/json

Request Path Params

Parameter	Data Type	Field Validations	Description
document_id	String	Should be a valid document id	Mandatory

Request Query Params

Parameter	Data Type	Field Validations	Description
einvoice-type	ENUM	SALES, PURCHASE, SALES_B2C	Default: SALES

Request Body

Parameter	Data Type	Field Validations	Description
Reason	String	Cannot be null	Mandatory. Reason for cancellation
Action	String	CANCEL	Mandatory, Action should be CANCEL for cancellation of a document

Sample Request

Request Body

{
    "Reason": "Wrong Invoice Amount",
    "Action": "CANCEL"
}

Response Status Codes

HTTP Status Code	Description
200	For a successful status check
400	For any kind of invalid payload issues
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
Uuid	String	NA	Unique document ID in e-Invoice, shared by LHDN for the document
Success	Boolean	true/false	Identifies whether the request processing was successful or not
ErrorDetails	Array	NA	Optional. List of error objects.

Sample Response (Success)

HTTP Status Code: 200

Response Body

{
    "Uuid": "MZQRKQKTXF6F4HJ7HW307B3J10",
    "Success": "true",
    "CancelDate": "2024-07-21 19:07:07",
    "ErrorDetails": null
}

Sample Response (Error)

HTTP Status Code: 200

Response Body - Idempotent response

{
    "Uuid": null,
    "Success": "false",
    "CancelDate": null,
    "ErrorDetails": [
        {
            "ErrorCode": "2272",
            "ErrorMessage": "EInvoice is already Cancelled",
            "ErrorSource": "CLEARTAX"
        }
    ]
}

API Validations

1. A valid document with {document_id} should be present in the system.

2. The document should be eligible for Cancellation, generated within last 72 hours

3. The TIN entity should be the generator of the Document, Seller for Invoice and Receiver for the Self Billed Invoice

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 cancel the document, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an Admin role for the particular TIN used in the request.