E-Invoice Cancellation & Rejection

Two cancellation approaches are available:

• Rejection Request Flow — A structured multi-step process where a buyer raises a rejection request, an admin reviews and approves it, and then the admin submits it to LHDN. Useful when internal approval tracking is required.
• Direct Cancellation Flow — Bypasses the rejection request record entirely. An admin directly sends the cancellation to LHDN using the e-invoice’s LHDN document UID. Useful for quick/bulk administrative cancellations.

This section documents the APIs for managing e-invoice rejection requests and submitting cancellations to the LHDN MyInvois portal.

Rejection Request Flow

Overview

In Malaysia’s MyInvois system, a validated e-invoice can only be cancelled within 72 hours of its validation datetime. BigLedger models this workflow through a structured rejection request process:

1. Buyer (customer) raises a rejection request — providing the reason and linking it to the validated e-invoice.
2. Admin reviews and approves/rejects the request — setting the system_approval_status and the processing_logic (what action to take after cancellation).
3. Admin triggers the LHDN submission — approved rejection requests are processed and submitted to LHDN MyInvois to cancel the e-invoice(s).

Base URL

All endpoints are relative to the tenant-scoped base path:

https://api.akaun.com/core2/tnt/dm/erp/e-invoice/request-rejections

Note: All API calls require a valid bearer authentication token in the Authorization header. The tenant code is resolved from the token.

Authentication & Permissions

These APIs use back-office endpoints (/backoffice-ep). The caller must have the appropriate role permission granted on their account.

Workflow Summary

Buyer                  Admin                    System
 │                      │                          │
 │ POST /backoffice-ep   │                          │
 │──────────────────►   │                          │
 │  (Submits rejection   │                          │
 │   request with        │                          │
 │   reason + doc refs)  │                          │
 │                       │                          │
 │                       │  Reviews request         │
 │                       │  Sets processing_logic   │
 │                       │  Sets system_approval_status
 │                       │                          │
 │                       │ PUT /backoffice-ep        │
 │                       │──────────────────────►   │
 │                       │  (Approves or rejects)   │
 │                       │                          │
 │                       │ POST /submit-to-lhdn/    │
 │                       │       backoffice-ep      │
 │                       │──────────────────────►   │
 │                       │  (Triggers LHDN          │
 │                       │   cancellation API)      │

API 1: Create Rejection Request

Buyer / Customer raises a rejection request for a validated e-invoice.

Endpoint

POST /core2/tnt/dm/erp/e-invoice/request-rejections/backoffice-ep
Content-Type: application/json
Authorization: Bearer <token>

Request Body

The request body wraps a single bl_fi_my_einvoice_request_rejection_internal_doc_hdr object:

{
  "bl_fi_my_einvoice_request_rejection_internal_doc_hdr": {
    "guid": "550e8400-e29b-41d4-a716-446655440000",
    "to_irb_doc_hdr_guid": "7b9e2c1a-3f4d-4e8b-a0c2-112233445566",
    "generic_doc_hdr_guid": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "einvoice_supplier_entity_hdr_guid": "c0ffee00-dead-beef-cafe-000000000001",
    "einvoice_buyer_entity_hdr_guid": "c0ffee00-dead-beef-cafe-000000000002",
    "server_doc_type": "INVOICE",
    "reason": "Incorrect tax amount applied to line item 3",
    "request_submitted_datetime": "2026-03-30T10:00:00+08:00",
    "doc_ccy": "MYR",
    "amount_txn": 1500.00,
    "txn_date": "2026-03-28T00:00:00+08:00",
    "document_ref_no": "INV-2026-0042",
    "status": "ACTIVE",
    "revision": "11223344-5566-7788-99aa-bbccddeeff00",
    "created_date": "2026-03-30T10:00:00+08:00",
    "updated_date": "2026-03-30T10:00:00+08:00"
  }
}

Required Fields

Optional Fields

System-Populated Fields (do not set manually)

Success Response

{
  "code": "OK",
  "data": {
    "bl_fi_my_einvoice_request_rejection_internal_doc_hdr": {
      "guid": "550e8400-e29b-41d4-a716-446655440000",
      "system_requestor_status": "REQUESTED",
      "system_processing_status": "IN-PROGRESS",
      ...
    }
  }
}

Side Effects

After successful creation, the system automatically updates the linked to_irb document’s blg_reject_request_datetime timestamp to the current time.

API 2: Update / Admin Approve Rejection Request

Admin reviews a rejection request and sets the approval decision and processing logic.

Endpoint

PUT /core2/tnt/dm/erp/e-invoice/request-rejections/backoffice-ep
Content-Type: application/json
Authorization: Bearer <token>

Request Body

{
  "bl_fi_my_einvoice_request_rejection_internal_doc_hdr": {
    "guid": "550e8400-e29b-41d4-a716-446655440000",
    "system_approval_status": "APPROVED",
    "processing_logic": "VOID_ORIGINAL_DOC",
    "revision": "aabbccdd-eeff-0011-2233-445566778899",
    "updated_date": "2026-03-30T11:00:00+08:00"
  }
}

Required Fields

Processing Logic Options

The processing_logic field controls what the system does after the LHDN cancellation is confirmed:

Status Reference

system_approval_status

system_requestor_status (read-only, set on creation)

system_processing_status

lhdn_cancellation_status (set after LHDN processing)

Side Effects

When system_approval_status is set to APPROVED and processing_logic is VOID_ORIGINAL_DOC or REGEN_NEW_EINVOICE, the system updates the linked to_irb document’s blg_cancellation_datetime to the current time (first approval only).

If approval is later reversed (set to something other than APPROVED), the blg_cancellation_datetime is cleared back to null.

Success Response

{
  "code": "OK",
  "data": {
    "bl_fi_my_einvoice_request_rejection_internal_doc_hdr": {
      "guid": "550e8400-e29b-41d4-a716-446655440000",
      "system_approval_status": "APPROVED",
      "processing_logic": "VOID_ORIGINAL_DOC",
      ...
    }
  }
}

API 3: Submit Approved Rejections to LHDN

Triggers the actual cancellation request(s) to the LHDN MyInvois API for all approved rejection records in the given list.

Endpoint

POST /core2/tnt/dm/erp/e-invoice/request-rejections/submit-to-lhdn/backoffice-ep
Content-Type: application/json
Authorization: Bearer <token>

Request Body

{
  "requestRejectionHdrGuids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660f9511-f30c-52e5-b827-557766551111"
  ]
}

Fields

Eligibility Criteria

Only rejection requests matching all of the following conditions are processed:

Records that are not yet approved, already completed, or missing processing_logic are ignored.

Processing Flow

1. Creates cancellation queue entries — Each eligible rejection record is enqueued as a MyEInvoiceGenDocToIrbCancellationQueueContainer.
2. Validates the cancellation window — The e-invoice must be in Valid status on LHDN and within 72 hours of its validation datetime.
3. Calls LHDN MyInvois API — Sends the cancellation request to LHDN for each eligible queue entry.
4. Executes processing logic — Based on the processing_logic set by the admin, executes the corresponding post-cancellation action (void document, regenerate e-invoice, create reversal doc, etc.).
5. Updates statuses — Sets system_processing_status to COMPLETED and lhdn_cancellation_status to either Cancelled or FAILED.

Success Response

Returns the updated list of rejection request containers after processing:

{
  "code": "OK",
  "data": [
    {
      "bl_fi_my_einvoice_request_rejection_internal_doc_hdr": {
        "guid": "550e8400-e29b-41d4-a716-446655440000",
        "system_processing_status": "COMPLETED",
        "lhdn_cancellation_status": "Cancelled",
        ...
      }
    }
  ]
}

Important Notes

• The LHDN cancellation window is 72 hours from the e-invoice’s validation datetime. Requests submitted after this window are rejected by LHDN.
• The e-invoice must have einvoice_document_status = Valid on LHDN to be eligible for cancellation.
• If a cancellation queue entry already exists in a SUBMISSION_FAILED state, it can be retried by calling this endpoint again with the same GUID.
• Email notifications are automatically sent on completion (success or failure) based on the notification configuration.

Complete Field Reference

Full list of all fields on bl_fi_my_einvoice_request_rejection_internal_doc_hdr:

Error Handling

The API returns standard BigLedger error responses. Common errors:

Direct Cancellation Flow

This flow bypasses the rejection request record entirely. An admin issues the cancellation command directly to LHDN using the e-invoice’s LHDN document UID and the internal to_irb header GUID. No rejection tracking record is created or required.

Use this flow when:

• You need to cancel an e-invoice immediately without an internal approval process.
• You are performing bulk cancellations across a date range.

Base URL

All endpoints are relative to:

/core2/tnt/dm/erp/e-invoice/direct-cancellation

Authentication & Permissions

The caller must also hold the OWNER or ADMIN role for:

• API_TNT_DM_ERP_MY_E_INVOICE_LHDN_INTEGRATION_OWNER
• API_TNT_DM_ERP_MY_E_INVOICE_LHDN_INTEGRATION_ADMIN

API 4: Direct Single Cancellation

Directly cancels a single e-invoice on LHDN by its document UID, bypassing any rejection request workflow.

Endpoint

POST /core2/tnt/dm/erp/e-invoice/direct-cancellation/submit-to-lhdn/backoffice-ep
Content-Type: application/json
Authorization: Bearer <token>

Request Body

{
  "toIrbHdrGuid": "550e8400-e29b-41d4-a716-446655440000",
  "documentUId": "ABC123XYZ",
  "reason": "Incorrect invoice amount — needs correction before reissuance"
}

Fields

Processing Flow

1. Calls the LHDN MyInvois cancellation API directly with the supplied documentUId and reason.
2. If the cancellation succeeds (cancellationSuccess = true), the internal to_irb document is refreshed to pull the latest e-invoice status from LHDN.
3. Returns the full LHDN cancellation result regardless of success or failure.

Success Response

{
  "code": "OK",
  "data": {
    "cancellationResp": {
      "uuid": "ABC123XYZ",
      "status": "Cancelled"
    },
    "request_url": "https://myinvois.hasil.gov.my/api/v1.0/documents/...",
    "request_body": "{...}",
    "request_response": "{...}",
    "request_error": null,
    "cancellationSuccess": true,
    "cancellationRequestValidationDto": {
      "isRequestValid": true,
      "reason": null
    }
  }
}

Failure Response (LHDN rejected the request)

{
  "code": "OK",
  "data": {
    "cancellationResp": null,
    "request_url": "https://myinvois.hasil.gov.my/api/v1.0/documents/...",
    "request_body": "{...}",
    "request_response": "{...}",
    "request_error": "Document is not eligible for cancellation",
    "cancellationSuccess": false,
    "cancellationRequestValidationDto": {
      "isRequestValid": false,
      "reason": "Passed 72 hours from validation date time"
    }
  }
}

Note: The HTTP status is always 200 OK. Check cancellationSuccess in the response body to determine whether the LHDN cancellation actually succeeded.

Response Fields

API 5: Bulk Direct Cancellation by Filter

Fetches all eligible e-invoices matching a date range filter and bulk-cancels them on LHDN in a single call.

Endpoint

POST /core2/tnt/dm/erp/e-invoice/direct-cancellation/submit-to-lhdn/by-filter/backoffice-ep
Content-Type: application/json
Authorization: Bearer <token>

Request Body

{
  "einvoiceDateFrom": "2026-03-01T00:00:00+08:00",
  "einvoiceDateTo": "2026-03-28T23:59:59+08:00",
  "validationDateFrom": "2026-03-01T00:00:00+08:00",
  "validationDateTo": "2026-03-28T23:59:59+08:00"
}

Fields

All four date fields are required. The API returns a 400 / error if any are missing.

Processing Flow

1. Queries all to_irb records whose e-invoice date and LHDN validation date fall within the specified ranges.
2. If no eligible documents are found, returns a 200 OK with an informational message.
3. For each eligible document, calls the LHDN MyInvois cancellation API.
4. Returns the aggregated list of LHDNCancellationDto results — one entry per processed e-invoice.

Success Response — Documents Found and Processed

{
  "code": "OK",
  "data": [
    {
      "cancellationResp": {
        "uuid": "DOC-UID-001",
        "status": "Cancelled"
      },
      "cancellationSuccess": true,
      "request_error": null,
      ...
    },
    {
      "cancellationResp": null,
      "cancellationSuccess": false,
      "request_error": "Document is not eligible for cancellation",
      ...
    }
  ]
}

Success Response — No Documents Found

{
  "code": "OK",
  "data": "No valid invoices found for the given criteria."
}

Important Notes

• Individual documents within the batch may succeed or fail independently. Always inspect the cancellationSuccess flag on each item in the returned array.
• The response array order corresponds to the order in which documents were fetched and processed.
• The same 72-hour validation window rule applies to each document in the batch.

Comparison: Rejection Request Flow vs Direct Cancellation Flow