Complete API reference for managing consolidated invoices in the E-Invoice system

Consolidated Invoices API

This section covers all consolidated invoice-related endpoints for creating, updating, retrieving, and managing consolidated invoices in the Malaysian e-invoicing system.

Authentication

All endpoints require authentication via API key:

X-API-Key: your-api-key-here

Base URL

/api

Get All Consolidated Invoices

Retrieve a paginated list of all consolidated invoices.

Endpoint

GET /api/consolidated-invoices

Headers

X-API-Key: your-api-key-here

Query Parameters

Standard pagination parameters are supported.

Response Example

{
  "meta": {
    "total": 3,
    "per_page": 10,
    "current_page": 1,
    "last_page": 1,
    "first_page": 1,
    "first_page_url": "/?page=1",
    "last_page_url": "/?page=1",
    "next_page_url": null,
    "previous_page_url": null
  },
  "data": [
    {
      "id": 27,
      "company_id": 2,
      "user_id": null,
      "invoice_code": "3",
      "external_id": null,
      "type": "CONSOLIDATED_INVOICE",
      "buyer": {
        "tin": "EI00000000010",
        "name": "General Public",
        "address": {
          "state": "14",
          "country": "MYS",
          "cityName": "NA",
          "postalZone": "NA",
          "addressLine0": "NA"
        },
        "partyType": "LOCAL_INDIVIDUAL",
        "contactNumber": "NA",
        "registrationType": "BRN",
        "registrationNumber": "NA",
        "sstRegistrationNumber": "NA"
      },
      "supplier": {
        "tin": "IG12345678901",
        "msic": "46510",
        "name": "Gaincue Retail",
        "email": "gaincueRetail@gmail.com",
        "address": {
          "state": "07",
          "country": "MYS",
          "cityName": "Bukit Mertajam",
          "postalZone": "14000",
          "addressLine0": "Company address full dummy 1"
        },
        "partyType": "LOCAL_INDIVIDUAL",
        "contactNumber": "+60 12345678",
        "registrationType": "NRIC",
        "registrationNumber": "991021081111",
        "sstRegistrationNumber": "NA",
        "businessActivityDescription": "sell pc parts",
        "tourismTaxRegistrationNumber": "NA"
      },
      "line_items": [
        {
          "id": "1",
          "unit": {
            "code": "EA",
            "count": 1,
            "price": 300
          },
          "taxAmount": 30,
          "taxDetails": [
            {
              "taxRate": {
                "percentage": 10
              },
              "taxType": "01",
              "taxAmount": 30,
              "taxableAmount": 300
            }
          ],
          "description": "25A-INV-00002-25A-INV-00004",
          "taxExemption": {
            "reason": "Consolidated Tax Exemption",
            "taxAmount": 0,
            "taxableAmount": 0
          },
          "originCountry": "MYS",
          "classifications": ["004"],
          "allowanceCharges": []
        }
      ],
      "delivery_details": null,
      "invoice_date_time": {
        "date": "2025-08-27T07:42:15.555+00:00",
        "time": "2025-08-27T07:42:15.555+00:00"
      },
      "foreign_currency": null,
      "billing_period": null,
      "payment": null,
      "pre_payment": null,
      "billing_reference_number": null,
      "invoice_level_allowance_charge": {},
      "additional_document_reference": null,
      "created_at": "2025-08-27T07:42:15.556+00:00",
      "updated_at": "2025-08-27T07:42:15.556+00:00",
      "invoice_code_with_prefix_and_digits": "25A-CINV-00003",
      "status": "AWAIT_SUBMISSION_TO_LHDN",
      "legal_monetary_total": {
        "excludingTax": 300,
        "includingTax": 330,
        "payableAmount": 330,
        "netAmount": 300,
        "discountValue": 0,
        "feeAmount": 0,
        "payableRoundingAmount": 0
      }
    }
  ]
}

Get Specific Consolidated Invoice

Retrieve details of a specific consolidated invoice.

Endpoint

GET /api/consolidated-invoices/:id

Headers

X-API-Key: your-api-key-here

Path Parameters

Parameter	Type	Description
`id`	integer	Consolidated invoice ID

Response Example

Returns the same structure as individual consolidated invoice objects in the "Get All Consolidated Invoices" response.

Error Responses

Not Found (404)

{
  "message": "Row not found",
  "name": "E_ROW_NOT_FOUND",
  "status": 404
}

Create Adjustment Note for Consolidated Invoice

Create an adjustment note for a specific consolidated invoice.

Endpoint

POST /api/consolidated-invoices/:id/adjustment-note

Headers

X-API-Key: your-api-key-here
Content-Type: application/json

Path Parameters

Parameter	Type	Description
`id`	integer	Consolidated invoice ID

Request Body

Field	Type	Required	Description
`targetInvoiceType`	string	Yes	Must be "CONSOLIDATED_INVOICE"
`type`	string	Yes	Adjustment note type: `CREDIT_NOTE`, `DEBIT_NOTE`
`adjustmentNoteCode`	number	Yes	Unique adjustment note code
`adjustmentNoteIssueDate`	string	Yes	Issue date (ISO 8601 format)
`lineItems`	array	Yes	Array of adjustment line items

Request Example

{
  "targetInvoiceType": "CONSOLIDATED_INVOICE",
  "type": "CREDIT_NOTE",
  "adjustmentNoteCode": 1,
  "adjustmentNoteIssueDate": "2025-08-05T00:00:00.000Z",
  "lineItems": [
    {
      "id": "item-1",
      "classifications": ["004"],
      "description": "Adjustment for consolidated invoice item",
      "unit": {
        "price": 100,
        "count": 2,
        "code": "EA"
      },
      "taxDetails": [
        {
          "taxType": "01",
          "taxRate": {
            "percentage": 0
          }
        }
      ],
      "taxExemption": {
        "taxableAmount": 50,
        "reason": "Partial tax exemption"
      },
      "allowanceCharges": [
        {
          "amount": 10,
          "reason": "Discount for early payment",
          "isCharge": false
        }
      ],
      "originCountry": "MYS"
    }
  ]
}

Response Examples

Success (200)

{
  "success": true,
  "message": "Successfully created adjustment note"
}

Error - Forbidden (403)

{
  "success": false,
  "message": "The consolidated invoice is not ready for adjustment notes"
}

Consolidated Invoice Data Structure

Main Consolidated Invoice Object

Field	Type	Description
`id`	number	Unique consolidated invoice identifier
`company_id`	number	Associated company ID
`user_id`	number\|null	Associated user ID
`invoice_code`	string	Invoice code
`external_id`	string\|null	External reference ID
`type`	string	Always "CONSOLIDATED_INVOICE"
`buyer`	object	Buyer information
`supplier`	object	Supplier information
`line_items`	array	Array of line items
`delivery_details`	object\|null	Delivery information
`invoice_date_time`	object	Invoice date and time
`foreign_currency`	object\|null	Foreign currency details
`billing_period`	object\|null	Billing period
`payment`	object\|null	Payment details
`pre_payment`	object\|null	Pre-payment details
`billing_reference_number`	string\|null	Billing reference
`invoice_level_allowance_charge`	object	Invoice-level allowances/charges
`additional_document_reference`	object\|null	Additional document references
`created_at`	string	Creation timestamp
`updated_at`	string	Last update timestamp
`invoice_code_with_prefix_and_digits`	string	Full invoice code with prefix
`status`	string	Invoice status
`legal_monetary_total`	object	Monetary totals

Invoice Date Time Object

Field	Type	Description
`date`	string	Invoice date (ISO 8601 format)
`time`	string	Invoice time (ISO 8601 format)

Legal Monetary Total Object

Field	Type	Description
`excludingTax`	number	Amount excluding tax
`includingTax`	number	Amount including tax
`payableAmount`	number	Total payable amount
`netAmount`	number	Net amount
`discountValue`	number	Total discount value
`feeAmount`	number	Total fee amount
`payableRoundingAmount`	number	Rounding amount

Line Item Object

Field	Type	Description
`id`	string	Line item identifier
`unit`	object	Unit details (code, count, price)
`taxAmount`	number	Total tax amount for the item
`taxDetails`	array	Array of tax details
`description`	string	Item description
`taxExemption`	object	Tax exemption details
`originCountry`	string	Country of origin (ISO 3166-1 alpha-3)
`classifications`	array	Array of classification codes
`allowanceCharges`	array	Array of allowance/charge details

Common Error Codes

Status Code	Description
`200`	OK - Request successful
`400`	Bad Request - Invalid request data
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Operation not allowed
`404`	Not Found - Resource not found
`422`	Unprocessable Entity - Validation errors

Important Notes

Consolidated Invoice Purpose: Consolidated invoices are used to combine multiple regular invoices into a single document for submission to MyInvois.
Type Field: Must always be set to "CONSOLIDATED_INVOICE" to distinguish from regular invoices.
Status Values: Common status values include:
- AWAIT_SUBMISSION_TO_LHDN: Ready for submission
- SUBMITTED: Successfully submitted to MyInvois
- VALID: Validated by LHDN
Party Types: Both buyer and supplier must have valid party type classifications.
Tax Exemptions: Consolidated invoices often have special tax exemption handling.
Line Item Descriptions: Often contain references to the original invoices being consolidated.
Date Format: All dates must be in ISO 8601 format.
MSIC Codes: Supplier must include valid Malaysian Standard Industrial Classification codes.
Registration Types: Support both BRN (Business Registration Number) and NRIC (National Registration Identity Card).
Country Codes: Use "MYS" for Malaysia (ISO 3166-1 alpha-3).

Consolidated Invoices API

On this page