Core Concepts

Before integrating with the BizCARE Books e-Invoicing API, familiarize yourself with the core domain concepts that shape how e-invoicing works in Malaysia.

Company

A Company represents your business entity registered for e-invoicing with LHDN (Lembaga Hasil Dalam Negeri). Each user account has one company.

A company record stores:

• TIN (Tax Identification Number) -- Your LHDN-issued tax ID (e.g., C20948240010)
• Registration number -- Your SSM business registration number or personal identification number
• Registration type -- One of BRN (Business Registration Number), NRIC (National ID), PASSPORT, or ARMY
• LHDN credentials -- A clientId and clientSecret pair obtained from the MyInvois portal, used to authenticate document submissions with LHDN
• Business details -- MSIC code, business activity description, SST registration number, address, and contact information

Your company must be fully set up before you can submit any invoices. Use GET /api/v1/companies and check the isCompanyReady flag to verify readiness.

Invoice Types

BizCARE supports four invoice types, each serving a different purpose:

Draft types (PENDING_FINALIZE_*) are working documents that cannot be submitted to LHDN. Change the type to INVOICE or SELF_BILLED_INVOICE when the invoice is ready for submission.

Adjustment Notes

Adjustment notes are corrections applied to a Valid invoice. They must always reference a parent invoice.

Each adjustment note has its own sequential code (separate from invoice codes) and contains line items describing the adjustment. To create an adjustment note, use POST /api/v1/invoices/:id/adjustment-note where :id is the parent invoice.

Consolidated Invoices

Consolidated invoices aggregate multiple transactions into a single LHDN submission. They are commonly used for:

• Daily POS (Point of Sale) sales summaries
• Batch processing of low-value transactions (under RM 10,000)
• Transactions where buyer details are not available

Consolidation runs monthly on the server (see Monthly consolidation). Invoice responses carry isTotalExceedOrEqual10k so you can see which side of the RM 10,000 line an invoice falls on.

Document Lifecycle

Every invoice and adjustment note follows a defined lifecycle:

Draft --> Ready --> Submitted --> Valid / Invalid
                                    |        |
                                Cancelled  Resubmit

1. Draft -- The document is created but not yet complete. The isReady flag is false.
2. Ready -- All required fields are populated. The isReady flag is true. The document can now be submitted.
3. Submitted -- The document has been sent to LHDN and is awaiting validation. LHDN typically validates within seconds to minutes.
4. Valid -- LHDN has accepted the document. It is now a legally binding e-invoice. Valid documents can be cancelled by providing a cancellation reason.
5. Invalid -- LHDN has rejected the document. The rejection reasons are available in the submitted document's failReason and failDetails fields. You can fix the issues and resubmit.

Buyer and Supplier

Every invoice contains two party objects representing the transaction participants:

• Supplier -- The party issuing the invoice. This is typically your company. The supplier object includes additional fields like msic (MSIC code), businessActivityDescription, and optionally bankAccount and exporterCertifiedNumber.
• Buyer -- The party receiving the goods or services. Your customer.

Both parties require:

When your company is set up, BizCARE can auto-populate the supplier (or buyer, for self-billed invoices) from your company profile.

Party types

Malaysian state codes

address.state takes one of these LHDN codes:

Issue dates

invoiceDateTime.date (invoices) and adjustmentNoteIssueDate (adjustment notes) must be today or up to 3 days back on the Malaysian calendar. A future date is always refused. An older date fails with 400 VALIDATION_ERROR ("Issue date must be today or within the last 3 days, and cannot be in the future."). The examples in these docs use <today, YYYY-MM-DD> for this reason. Replace it with a real date in that window.

invoiceDateTime.time with a zone marker (14:30:00Z) is that exact instant. Without a marker (14:30:00) it is read as Malaysian time.

Line Items

Line items represent individual goods or services on an invoice. Each line item contains:

Tax Details

Each line item must specify at least one tax detail entry:

{
  "taxType": "01",
  "taxRate": {
    "percentage": 10
  }
}

The taxRate object supports either percentage (e.g., 10 for 10%) or ratePerUnit (a fixed amount per unit), depending on the tax type.

Tax Types

Malaysia's e-invoicing system uses the following tax type codes:

LHDN Document Statuses

After submission to LHDN, each document is tracked with one of four statuses:

BizCARE automatically polls LHDN for status updates after submission (every 60 seconds while LHDN reports "in progress", then a half-hourly sweep for anything still Submitted after 10 minutes), and pushes changes to your webhooks. You can check the current status at any time: the latestSubmission object on GET /api/v1/invoices/:id carries it, and GET /api/v1/invoices/:id/submitted-documents gives the full history. POST /api/v1/submitted-documents/sync-status forces an immediate re-check.

When a document is marked Invalid, the failDetails field contains the LHDN validation errors in a structured format, allowing you to identify and fix the issue before resubmitting.