# 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
```

### 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

```json
{
    "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    | <p>NA<br></p>     | 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

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

### Sample Response (Error)

HTTP Status Code: 200

Response Body - Idempotent response

```json
{
    "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.
4. Rate Limit: The below rate limits are in line with those applied by LHDN.&#x20;

   **Production - 12 API calls per minute with a burst capacity of 2 API calls**

   **Sandbox - 4 API calls per minute with a burst capacity of 2 API calls**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cleartax.in/cleartax-docs/e-invoicing-malaysia-api/e-invoicing-malaysia-api-reference/api-lists/cancel-e-invoice.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.