Invoices API

This section covers all invoice-related endpoints for creating, updating, retrieving, and managing 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

Create Invoice

Create a new invoice in the system.

Endpoint

POST /api/invoices

Headers

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

Request Body

Field	Type	Required	Description
`submitImmediately`	boolean	No	Whether to submit the invoice immediately after creation
`isReady`	boolean	No	Whether the invoice is ready for submission
`type`	string	Yes	Invoice type: `INVOICE`, `SELF_BILLED_INVOICE`, `PENDING_FINALIZE_INVOICE`, `PENDING_FINALIZE_SELF_BILLED_INVOICE`
`code`	number	Yes	Invoice code (must be unique for the year)
`issueDateTime`	string	Yes	Invoice issue date and time (ISO 8601 format)
`buyer`	object	Conditional	Buyer information (required for `INVOICE` type)
`supplier`	object	Conditional	Supplier information (required for `SELF_BILLED_INVOICE` type)
`lineItems`	array	Yes	Array of line items

Buyer Object

Field	Type	Required	Description
`type`	string	Yes	Party type: `LOCAL_INDIVIDUAL`, `LOCAL_EXEMPTED_ENTITY`, `LOCAL_BUSINESS_AGENT_DEALER_DISTRIBUTOR`, `FOREIGNER_BUSINESS`, `FOREIGNER_INDIVIDUAL`
`name`	string	Yes	Buyer name
`tin`	string	No	Tax identification number
`registration`	object	Yes	Registration details
`registration.type`	string	Yes	Registration type: `NRIC`, `BRN`, `PASSPORT`
`registration.number`	string	Yes	Registration number
`contactNumber`	string	No	Contact phone number
`address`	object	Yes	Address details
`address.line1`	string	Yes	Address line 1
`address.city`	string	Yes	City name
`address.state`	string	Yes	State code (Malaysian state codes)
`address.zipCode`	string	Yes	Postal code
`address.country`	string	Yes	Country code (ISO 3166-1 alpha-3)

Line Item Object

Field	Type	Required	Description
`id`	string	Yes	Unique line item identifier
`description`	string	Yes	Item description
`classifications`	array	Yes	Array of classification codes
`unit`	object	Yes	Unit details
`unit.code`	string	Yes	Unit code (e.g., "EA" for each)
`unit.price`	number	Yes	Unit price
`unit.count`	number	Yes	Quantity
`taxDetails`	array	Yes	Array of tax details
`taxDetails[].taxType`	string	Yes	Tax type code
`taxDetails[].taxRate.percentage`	number	Yes	Tax rate percentage
`originCountry`	string	Yes	Country of origin (ISO 3166-1 alpha-3)

Request Example

{
  "submitImmediately": false,
  "isReady": true,
  "type": "INVOICE",
  "code": 6,
  "issueDateTime": "2025-07-15T14:41:23.000Z",
  "buyer": {
    "type": "LOCAL_INDIVIDUAL",
    "name": "Sean",
    "registration": {
      "type": "NRIC",
      "number": "abc21234"
    },
    "contactNumber": "016-8985360",
    "address": {
      "line1": "34a, Jalan ABC 123",
      "city": "Bukit Jalil",
      "state": "14",
      "zipCode": "56420",
      "country": "MYS"
    }
  },
  "lineItems": [
    {
      "id": "item-1-id",
      "description": "test",
      "classifications": ["007"],
      "unit": {
        "code": "EA",
        "price": 88.88,
        "count": 1
      },
      "taxDetails": [
        {
          "taxType": "01",
          "taxRate": {
            "percentage": 10
          }
        }
      ],
      "originCountry": "MYS"
    }
  ]
}

Response

Success (200)

{
  "success": true,
  "message": "Created successfully",
  "data": {
    "id": 38
  }
}

Validation Error (422)

{
  "message": "Validation failure",
  "error": {
    "status": 422,
    "code": "E_VALIDATION_ERROR",
    "messages": [
      {
        "message": "When invoice type is INVOICE, buyer is required",
        "rule": "conditional required",
        "field": "buyer"
      }
    ]
  }
}

Duplicate Invoice Code (409)

{
  "success": false,
  "message": "Invoice code already exists for current year"
}

Get All Invoices

Retrieve a paginated list of all invoices.

Endpoint

GET /api/invoices

Headers

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

Query Parameters

Standard pagination parameters are supported.

Response Example

{
  "meta": {
    "total": 7,
    "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": 71,
      "company_id": 2,
      "user_id": 1,
      "consolidated_invoice_id": null,
      "is_submitted_to_lhdn": false,
      "is_ready": false,
      "invoice_code": "7",
      "external_id": null,
      "type": "INVOICE",
      "buyer": {
        "tin": "IG40023601100",
        "name": "Ricky 3456",
        "email": "leonheng2000@gmail.com",
        "address": {
          "state": "07",
          "country": "MYS",
          "cityName": "Bukit Mertajam",
          "postalZone": "14000",
          "addressLine0": "123@gmail.com"
        },
        "partyType": "LOCAL_INDIVIDUAL",
        "contactNumber": "0168985360",
        "registrationType": "NRIC",
        "registrationNumber": "930723075219"
      },
      "line_items": [
        {
          "id": "1",
          "unit": {
            "code": "EA",
            "count": 1,
            "price": 10
          },
          "taxAmount": 1,
          "taxDetails": [
            {
              "taxRate": {
                "percentage": 10
              },
              "taxType": "01",
              "taxAmount": 1,
              "taxableAmount": 10
            }
          ],
          "description": "test",
          "originCountry": "MYS",
          "classifications": ["022"]
        }
      ],
      "final_adjusted_amount": 11,
      "status": "Draft",
      "legal_monetary_total": {
        "excludingTax": 10,
        "includingTax": 11,
        "payableAmount": 11,
        "netAmount": 10,
        "discountValue": 0,
        "feeAmount": 0,
        "payableRoundingAmount": 0
      },
      "created_at": "2025-09-22T05:32:19.534+00:00",
      "updated_at": "2025-09-22T05:55:37.798+00:00"
    }
  ]
}

Get Specific Invoice

Retrieve details of a specific invoice.

Endpoint

GET /api/invoices/:id

Headers

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

Path Parameters

Parameter	Type	Description
`id`	integer	Invoice ID

Response

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

Update Invoice

Update an existing invoice.

Endpoint

PUT /api/invoices/:id

Headers

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

Path Parameters

Parameter	Type	Description
`id`	integer	Invoice ID

Request Body

Similar structure to the Create Invoice request body. You can update any of the invoice fields.

Request Example

{
  "isReady": true,
  "type": "INVOICE",
  "buyer": {
    "name": "BizCARE",
    "tin": "IG12345678",
    "registration": {
      "type": "NRIC",
      "number": "12345678"
    },
    "type": "LOCAL_INDIVIDUAL",
    "contactNumber": "+6012345678",
    "address": {
      "line1": "Address Line 0 dummy",
      "state": "14",
      "country": "MYS",
      "city": "George Town",
      "zipCode": "15000"
    }
  },
  "issueDateTime": "2025-07-15T14:41:23.000Z",
  "lineItems": [
    {
      "id": "item-1-id",
      "description": "test",
      "classifications": ["007"],
      "unit": {
        "code": "EA",
        "price": 100,
        "count": 1
      },
      "taxDetails": [
        {
          "taxType": "01",
          "taxRate": {
            "percentage": 10
          }
        }
      ],
      "originCountry": "MYS"
    }
  ]
}

Delete Invoice

Delete a specific invoice.

Endpoint

DELETE /api/invoices/:id

Headers

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

Path Parameters

Parameter	Type	Description
`id`	integer	Invoice ID

Response Example

{
  "success": true,
  "message": "Invoice deleted successfully"
}

Submit Invoice to MyInvois

Submit an invoice to the MyInvois system for validation and processing.

Endpoint

POST /api/invoices/:id/submit-to-myinvois

Headers

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

Path Parameters

Parameter	Type	Description
`id`	integer	Invoice ID

Request Body

Empty JSON object: {}

Response Examples

Success (200)

{
  "success": true,
  "message": "Submitted successfully"
}

Error (400)

{
  "success": false,
  "message": "Failed to submit, please try again"
}

Cancel Latest Submitted Document

Cancel the latest submitted document for an invoice (must be within 72 hours of submission).

Endpoint

POST /api/invoices/:id/cancel-latest-invoice-submitted

Headers

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

Path Parameters

Parameter	Type	Description
`id`	integer	Invoice ID

Response Examples

Success (200)

{
  "success": true,
  "message": "Cancelled submitted document successfully"
}

Error - No Submitted Document (403)

{
  "success": false,
  "message": "The invoice does not have any submitted document."
}

Error - Already Cancelled (403)

{
  "success": false,
  "message": "The latest submitted document of the invoice has already been cancelled/invalid."
}

Error - 72-Hour Limit Exceeded (403)

{
  "success": false,
  "message": "The latest submitted document of the invoice has been submitted more than 72 hours ago. Submitted documents can only be cancelled within 72 hours."
}

Create Adjustment Note

Create an adjustment note (credit note or debit note) for a specific invoice.

Endpoint

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

Headers

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

Path Parameters

Parameter	Type	Description
`id`	integer	Invoice ID

Request Body

Field	Type	Required	Description
`targetInvoiceType`	string	Yes	Type of target invoice: `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": "INVOICE",
  "type": "CREDIT_NOTE",
  "adjustmentNoteCode": 123,
  "adjustmentNoteIssueDate": "2023-08-01T00:00:00.000Z",
  "lineItems": [
    {
      "id": "item-1",
      "classifications": ["001"],
      "description": "Adjustment for invoice item",
      "unit": {
        "price": 100,
        "count": 2,
        "code": "EA"
      },
      "taxDetails": [
        {
          "taxType": "06",
          "taxRate": {
            "percentage": 6
          }
        }
      ],
      "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 - Invoice Waiting Validation (403)

{
  "success": false,
  "message": "The invoice has been submitted but not yet being validated by LHDN or latest submission result status is not valid."
}

Error - Invoice Not Submitted (403)

{
  "success": false,
  "message": "The invoice has not been submitted."
}

Get Submitted Documents

Retrieve all submitted documents associated with an invoice.

Endpoint

GET /api/invoices/:id/submitted-documents

Headers

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

Path Parameters

Parameter	Type	Description
`id`	integer	Invoice ID

Get Specific Submitted Document

Retrieve details of a specific submitted document.

Endpoint

GET /api/invoices/:id/submitted-documents/:submitted_document_id

Headers

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

Path Parameters

Parameter	Type	Description
`id`	integer	Invoice ID
`submitted_document_id`	integer	Submitted document ID

Common Error Codes

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

Important Notes

Date Format: All dates must be in ISO 8601 format (e.g., "2025-07-15T14:41:23.000Z")
Tax Types: Common Malaysian tax types:
- 01: SST (Sales and Service Tax)
- 02: Service Tax
- 03: Tourism Tax
- 06: Not Applicable
Registration Types:
- NRIC: National Registration Identity Card (for Malaysian individuals)
- BRN: Business Registration Number (for businesses)
- PASSPORT: Passport number (for foreign individuals)
Country Code: Use "MYS" for Malaysia (ISO 3166-1 alpha-3)
State Codes: Use Malaysian state codes (e.g., "14" for Penang, "07" for Perak)
Invoice Codes: Must be unique within the company for each calendar year
72-Hour Rule: Submitted documents can only be cancelled within 72 hours of submission

Invoices API

On this page