Create Document(s) - BeaconX e-Invoice API

This endpoint allows source systems to create eInvoice from provided invoice document data. Depending on the response, documents are inserted or rejected from system under the following scenarios:

"in_queue" - Document under this status means it is accepted and currently in queue to be submitted to IRBM.

"attention" - Document under this status means it is accepted but failed validation. Resubmitting will be replace with latest information based on reference_number.

"rejected" - Document under this status means it is rejected and not recorded in system. Data will need to be fixed and resubmitted again.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/json

array of:

supplier

object (Supplier)

optional

Supplier Object.

code

string

required

Master List code to be used as mapping. If this is provided and master list is used, you may leave the following fields blank (empty string ""). If code is provided and any of the following fields are also provided, your provided values will prevail and only those left as empty string will be mapped to the master list.

name

string

required

Full Name / Company Name as per IC / Registrar

tin

string

required

Tax Identification Number (TIN) issued by LHDN

EI0000000010 - General Public (Use in consolidation or when only IC is available)
EI0000000020 - for foreign (non Malaysian) buyers
EI0000000030 - for foreign (non Malaysian) suppliers
EI0000000040 - for buyers that belong to categories of Government, Authorities, Statutories or exempt institutions without TIN

id_type

string

required

Use either "BRN", "NRIC", "PASSPORT" or "ARMY"

id_number

string

required

Identification Number of Tax Payer (e.g. Business Registraion Number or NRIC)

string

required

A valid email address to receive e-Receipt / e-Invoice

phone

string

required

Phone Number (e.g. 60312345678)

address1

string

required

Address Line 1

address2

string

required

Address Line 2

address3

string

required

Address Line 3

city

string

required

City

postcode

string

required

Postcode

state

string

required

State Code

Refer to https://sdk.myinvois.hasil.gov.my/codes/state-codes/

country

string

required

Country Code. Use "MYS" for Malaysia

Refer to https://sdk.myinvois.hasil.gov.my/codes/countries/

sst_number

string

required

SST Registration No. Use "NA" if not applicable.

ttx_number

string

required

Tourism Tax Registration No. Use "NA" if not applicable.

msic1

string

required

MSIC Code relevant to the items sold / business activities. Use "00000" for self-billed international supplier or where multiple MSIC codes is applicable.

See full list of codes: https://sdk.myinvois.hasil.gov.my/codes/msic-codes/

msic1_desc

string

required

Business Activity Description based on MSIC Code. Use "NA" for self-billed international supplier.

is_foreign

string

required

Indicate if Tax Payer is Foreign. (1 for true, 0 for false)

buyer

object (Buyer)

required

Buyer Object.

is_foreign

boolean

deprecated

[Deprecated] Please include this field and set as empty string : ""

Default:

false

string

required

A valid email address to receive e-Receipt / e-Invoice. If not available, leave it as empty string (e.g. "")

tin

string | null

required

Tax Identification Number (TIN) issued by LHDN

name

string | null

required

Full Name / Company Name as per IC / Registrar

id_type

string | null

required

Use either "BRN", "NRIC", "PASSPORT" or "ARMY"

id_number

string | null

required

Identification Number of Tax Payer (e.g. Business Registraion Number or NRIC)

phone

string

required

Phone Number (e.g. 60312345678)

address1

string | null

optional

Address Line 1

address2

string

required

Address Line 2

state

string

required

State Code

Refer to https://sdk.myinvois.hasil.gov.my/codes/state-codes/

country

string

required

Country Code. Use "MYS" for Malaysia

Refer to https://sdk.myinvois.hasil.gov.my/codes/countries/

city

string

required

City

postcode

string

required

Postcode

address 3

string

required

Address Line 3

sst_number

string

required

SST Registration No. Use "NA" if not applicable.

code

string

required

Default:

gen_random_uuid()

membership_id

string

required

[Optional] You may leave this blank if unused (empty string : "")

shipping

object (Shipping)

required

Shipping Recipient Object. Optional.

code

string

required

If buyer master list is synchronized to middleware, the buyer code can be used to auto populate all related buyer fields. Therefore only the "code" field will be passed over and the rest are left out.

id_type

string

required

Use either "BRN", "NRIC", "PASSPORT" or "ARMY"

tin

string

required

Tax Identifier Number (TIN) of buyer

id_number

string

required

NRIC/Passport/BRN of the Buyer

name

string

required

Full Name / Company Name as per IC / Registrar

string

required

address1

string

required

Address Line 1

address2

string

required

Address Line 2

address3

string

required

Address Line 3

city

string

required

City

postcode

string

required

Postcode

state

string

required

State

00 All States
01 Johor
02 Kedah
03 Kelantan
04 Melaka
05 Negeri Sembilan
06 Pahang
07 Pulau Pinang
08 Perak
09 Perlis
10 Selangor
11 Terengganu
12 Sabah
13 Sarawak
14 Wilayah Persekutuan Kuala Lumpur
15 Wilayah Persekutuan Labuan
16 Wilayah Persekutuan Putrajaya
17 Not Applicable

country

string

required

Country. Default to "MYS"

Refer to https://sdk.myinvois.hasil.gov.my/codes/countries/ for full list

annex

object

required

Annexure for Import/Export of Goods. Optional

custom_form_number

string

required

incoterms

string

required

fta

string

required

certified_exporter_number

string

required

custom_k2_number

string

required

other_charges_description

string

required

other_charges_amount

string

required

status

string

required

"valid", "cancelled". "valid" indicates to middleware that this document shall be processed in queue to send to LHDN at soonest available. "draft" will remain in middleware until updated to "valid"

source

string

required

[Optional but field must be included in JSON]
Label for source system name, only used for internal record purpose. Defaults to "ERP".

type

string

required

Type of e-Invoice Document. Defaults to "01" for Invoice type.

01 Invoice
02 Credit Note
03 Debit Note
04 Refund Note
11 Self-billed Invoice
12 Self-billed Credit Note
13 Self-billed Debit Note
14 Self-billed Refund Note

reference_number

string

required

Internal Unique ID for ease of matching. If source system does not have

invoice_number

string

required

Document Number (Invoice / CN /DN / RN #)

original_einvoice_ref_number

string

required

[Optional but field must be included in JSON]
When issuing CN / DN / RN, reference to the original document number is supported. Use comma to separate multiple Invoice Numbers.

*Use "NA" when issuing CN / DN / RN original Invoice is not available or is not a validated eInvoice.

You may use either LHDN Unique ID / invoice_number / reference_number for this value.

original_einvoice_inv_number

string

optional

[Optional]
Used when printing in CN/DN/RN. If filled, PDF printout will display this instead of original_einvoice_ref_number.

po_number

string

required

[Optional but field must be included in JSON]
Purchase Order (PO) Number for internal record purpose.

pos_id

string

required

[Optional but field must be included in JSON]
Point of Sale (POS) Terminal ID. Optional

created_at

string

required

[Optional but field must be included in JSON]
Date / Time document was created in source system.

Format "YYYY-MM-DD HH:ii:ss". Where time is not available, use "YYYY-MM-DD"

issued_at

string

required

Document date (e.g. Invoice Date/Time)

Format "YYYY-MM-DD HH:ii:ss". Where time is not available, use "YYYY-MM-DD"

outlet_code

string

required

[Optional] Outlet / Branch code to link document to outlet.

dept_code

string

required

[Optional] Department code to link document to department.

system_company_name

string

optional

[Optional] Additional field to indicate corresponding Company Name from external source system

system_company_id

string

optional

[Optional] Additional field to indicate corresponding Company ID from external source system

outlet_id

string

optional

[Optional] Additional field to indicate corresponding Outlet ID from external source system

dept_id

string

optional

[Optional] Additional field to indicate corresponding Department ID from external source system

job_type

string

optional

[Optional] Additional field to indicate corresponding Job Type from external source system

currency_code

string

required

Currency Code. Defaults to "MYR"

Refer to https://sdk.myinvois.hasil.gov.my/codes/currencies/ for full list

currency_rate

number

required

Foreign Exchange Rate. Defaults to 1.0

frequency

string

required

[Optional but field must be included in JSON]
Frequency of Billing Period.

billing_period_start

string

required

[Optional but field must be included in JSON]
Billing period start date. Format YYYY-MM-DD.

billing_period_end

string

required

[Optional but field must be included in JSON]
Billing period end date. Format YYYY-MM-DD.

subtotal

number

required

Sum of all line items subtotal

*This value is before invoice level discounts and fees

discount_rate

number

deprecated

Discount rate % where applicable. Invoice level.

discount_amount

number

required

Additional Discount amount where applicable. Invoice level.

Note: This discount is before the final total and is after tax. It does not affect the tax calculation.

service_fee_rate

number

deprecated

Service / Charge Fees rate where applicable. Invoice level.

service_fee_amount

number

required

Additional Service / Charge Fees amount where applicable. Invoice level.

Note: This additional charge is before the final total and is after tax. It does not affect the tax calculation.

total_excl_tax

number

required

= subtotal - discount_amount (invoice level) + fee_amount (invoice level)

sales_tax_amount

number

required

Sum of line items Sales Tax amount

service_tax_amount

number

required

Sum of line items Service Tax amount

gst_amount

number

required

Sum of line items GST amount

ttx_amount

number

required

Sum of line item Tourism Tax amount

hvgt_amount

number

required

Sum of line item High Value Goods Tax amount

lvst_amount

number

required

Sum of line item Low Value Sales Tax amount

total_tax_amount

number

required

Sum of all tax types amount

total_incl_tax

number

required

= total_excl_tax + total_tax_amount

rounding

number

required

Rounding Adjustment of total_incl_tax to nearest RM 0.05

total_payable_amount

number

required

= total_incl_tax + rounding

payment_mode

string

required

[Optional but field must be included in JSON]
Applicable for retail purchases.

01 Cash
02 Cheque
03 Bank Transfer
04 Credit Card
05 Debit Card
06 e-Wallet / Digital Wallet
07 Digital Bank
08 Others

suppliers_bank_account_number

string

required

[Optional but field must be included in JSON]
Supplier's Bank Account Number that facilitates payment, where applicable.

payment_terms

string

required

[Optional but field must be included in JSON]
An agreed-upon payment terms and conditions. e.g. "Cash Upfront"

prepayment_amount

number

required

[Optional but field must be included in JSON]
Amount paid upfront. Default to 0

prepayment_datetime

string

required

[Optional but field must be included in JSON]
Date/Time of amount paid upfront.

prepayment_reference_number

string

required

[Optional but field must be included in JSON]
Transaction reference number of prepayment.

bill_reference_number

string

required

[Optional but field must be included in JSON]
Bill reference number.

footer_notes

string

optional

[Optional]
Invoice footer notes to be included in invoice for PDF printout

so_number

string

optional

[Optional]
Sales Order number for internal reference - Used in PDF printout

do_number

string

optional

[Optional]
Delivery Order number for internal reference - Used in PDF printout

template

string

optional

[Optional]
Template name of the invoice format. - Used for PDF printout. Defaults to "default".

created_by

string

required

[Optional but field must be included in JSON]
The email address of the user to be informed when validation error occurs.

items

array [object {34}]

required

Array of item objects. Minimum 1 item per document.

string

required

Line item identifier

classification

string

required

Classification code of line item. For multiple classification use comma to separate ","

product_tariff_code

string

required

[Optional but field must be included in JSON]
For export/import of goods, HS Code to be filled.

code

string

required

[Optional but field must be included in JSON]
Product/item/service code for internal reference.

description

string

required

Description of line item. (Max 300 chars)

long_description

string

required

[Optional but field must be included in JSON]
To be used in PDF printout template

quantity

number

required

Quantity

measurement

string

required

Unit of Measure for Quantity (.e.g "PCS")

Refer https://sdk.myinvois.hasil.gov.my/codes/unit-types/

unit_price

number

required

Unit price of item

subtotal

number

required

= unit_price * quantity

discount_rate

number

required

Discount Rate % where applicable.

Range in decimals 0-1.

discount_amount

number

required

Discount Amount where applicable.

service_fee_rate

number

required

Additional Service / Charge Fee % where applicable.Range in decimals 0-1.

service_fee_amount

number

required

Additional Service / Charge Amount where applicable.

total_excl_tax

number

required

= subtotal - discount_amount + fee_amount + charge_amount

sales_tax_rate

number

required

Sales Tax %

Range in decimals 0-1.

sales_tax_amount

number

required

Sales Tax amount

service_tax_rate

number

required

Service Tax %

Range in decimals 0-1.

service_tax_amount

number

required

Service Tax amount

gst_rate

number

required

GST Rate %

Range in decimals 0-1.

gst_amount

number

required

GST Amount

ttx_rate

number

required

Tourism Tax Rate %

Range in decimals 0-1.

ttx_amount

number

required

Tourism Tax Amount

hvgt_rate

number

required

High Value Goods Tax Rate %

Range in decimals 0-1.

hvgt_amount

number

required

High Value Goods Tax Amount

lvst_rate

number

required

Low Value Sales Tax Rate %

Range in decimals 0-1.

lvst_amount

number

required

Low Value Sales Tax Amount

total_tax_amount

number

required

Sum of all tax types amount

total_incl_tax

number

required

= total_excl_amount + total_tax_amount

details_tax_exemption

string

required

[Optional but field must be included in JSON]
Details related to tax exemption

tax_exempt_amount

number

required

Total Amount subject to Tax Exemption

country_of_origin

string

required

[Optional but field must be included in JSON]
For import/export of goods, specify the country of origin

total_sales

number

optional

Total Sales Amount (For Concession Use Only) - Used in PDF printout

commission_rate

number

optional

Total Commission Rate % (For Concession Use Only) - Used in PDF printout

Example

{
  "supplier": {
    "code": "",
    "id_type": "BRN",
    "tin": "C0123456789",
    "id_number": "201900000000",
    "name": "BEACON SYSTEMS SDN BHD",
    "email": "info@beaconx.com.my",
    "address1": "1, Jalan Beacon",
    "address2": "",
    "address3": "",
    "city": "Kuala Lumpur",
    "postcode": "57000",
    "state": "14",
    "country": "MYS",
    "sst_number": "NA",
    "ttx_number": "",
    "phone": "",
    "msic1": "00000",
    "msic1_desc": "NOT APPLICABLE",
    "is_foreign": "true"
  },
  "buyer": {
    "code": "",
    "id_type": "BRN",
    "tin": "C61901366810",
    "id_number": "201903007118",
    "name": "MY COMPANY SDN BHD",
    "email": "kendall.purdy@reilly.net",
    "address1": "72684 Murl Light Apt. 668",
    "address2": "",
    "address3": "",
    "city": "Lake Tedfort",
    "postcode": "29311",
    "state": "01",
    "country": "MYS",
    "sst_number": "W10-1060-26389071",
    "phone": "0125168978",
    "membership_id": "",
    "is_foreign": "false"
  },
  "shipping": {
    "code": "",
    "id_type": "",
    "tin": "",
    "id_number": "",
    "name": "",
    "email": "",
    "address1": "",
    "address2": "",
    "address3": "",
    "city": "",
    "postcode": "",
    "state": "",
    "country": "MYS"
  },
  "annex": {
    "custom_form_number": "",
    "incoterms": "",
    "fta": "",
    "certified_exporter_number": "",
    "custom_k2_number": "",
    "other_charges_description": "",
    "other_charges_amount": ""
  },
  "status": "valid",
  "source": "ERP",
  "type": "01",
  "reference_number": "INV/6990761",
  "invoice_number": "INV/6990761",
  "original_einvoice_ref_number": "",
  "original_einvoice_inv_number": "",
  "po_number": "PO/8555",
  "pos_id": "",
  "created_at": "",
  "issued_at": "2024-10-21",
  "posted_at": "2024-10-23",
  "system_company_name": "",
  "system_company_id": "",
  "outlet_id": "",
  "outlet_code": "HQ",
  "dept_id": "",
  "dept_code": "",
  "job_type": "",
  "created_by": "user@beaconx.com.my",
  "currency_code": "MYR",
  "currency_rate": 1,
  "frequency": "",
  "billing_period_start": "",
  "billing_period_end": "",
  "subtotal": 447.92,
  "discount_rate": 0,
  "discount_amount": 0,
  "total_excl_tax": 447.92,
  "sales_tax_amount": 0,
  "service_tax_amount": 0,
  "gst_amount": 0,
  "ttx_amount": 0,
  "hvgt_amount": 0,
  "lvst_amount": 0,
  "exempt_amount": 0,
  "total_tax_amount": 0,
  "total_incl_tax": 200,
  "service_fee_rate": 0,
  "service_fee_amount": 0,
  "rounding": 0,
  "total_payable_amount": 200,
  "payment_mode": "",
  "suppliers_bank_account_number": "",
  "payment_terms": "",
  "prepayment_amount": "",
  "prepayment_datetime": "",
  "prepayment_reference_number": "",
  "bill_reference_number": "",
  "footer_notes": "",
  "so_number": "",
  "do_number": "",
  "template": "",
  "items": [
    {
      "details_tax_exemption": "",
      "tax_exempt_amount": 0,
      "id": "1",
      "classification": "022",
      "product_tariff_code": "",
      "code": "",
      "description": "1-3000",
      "long_description": "",
      "quantity": 1,
      "measurement": "EA",
      "unit_price": 100,
      "subtotal": 100,
      "discount_rate": 0,
      "discount_amount": 0,
      "service_fee_rate": 0,
      "service_fee_amount": 0,
      "total_excl_tax": 100,
      "sales_tax_rate": 0,
      "sales_tax_amount": 0,
      "service_tax_rate": 0,
      "service_tax_amount": 0,
      "gst_rate": 0,
      "gst_amount": 0,
      "ttx_rate": 0,
      "ttx_amount": 0,
      "hvgt_rate": 0,
      "hvgt_amount": 0,
      "lvst_rate": 0,
      "lvst_amount": 0,
      "total_incl_tax": 100,
      "country_of_origin": "",
      "total_sales": "",
      "commission_rate": ""
    },
    {
      "details_tax_exemption": "",
      "tax_exempt_amount": 0,
      "id": "2",
      "classification": "022",
      "product_tariff_code": "",
      "code": "",
      "description": "1-4000",
      "long_description": "",
      "quantity": 1,
      "measurement": "EA",
      "unit_price": 100,
      "subtotal": 100,
      "discount_rate": 0,
      "discount_amount": 0,
      "service_fee_rate": 0,
      "service_fee_amount": 0,
      "total_excl_tax": 100,
      "sales_tax_rate": 0,
      "sales_tax_amount": 0,
      "service_tax_rate": 0,
      "service_tax_amount": 0,
      "gst_rate": 0,
      "gst_amount": 0,
      "ttx_rate": 0,
      "ttx_amount": 0,
      "hvgt_rate": 0,
      "hvgt_amount": 0,
      "lvst_rate": 0,
      "lvst_amount": 0,
      "total_incl_tax": 100,
      "country_of_origin": "",
      "total_sales": "",
      "commission_rate": ""
    }
  ]
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://einvoice-api.beaconx.com.my/einvoices/create' \
--header 'Content-Type: application/json' \
--data-raw '{
  "supplier": {
    "code": "",
    "id_type": "BRN",
    "tin": "C0123456789",
    "id_number": "201900000000",
    "name": "BEACON SYSTEMS SDN BHD",
    "email": "info@beaconx.com.my",
    "address1": "1, Jalan Beacon",
    "address2": "",
    "address3": "",
    "city": "Kuala Lumpur",
    "postcode": "57000",
    "state": "14",
    "country": "MYS",
    "sst_number": "NA",
    "ttx_number": "",
    "phone": "",
    "msic1": "00000",
    "msic1_desc": "NOT APPLICABLE",
    "is_foreign": "true"
  },
  "buyer": {
    "code": "",
    "id_type": "BRN",
    "tin": "C61901366810",
    "id_number": "201903007118",
    "name": "MY COMPANY SDN BHD",
    "email": "kendall.purdy@reilly.net",
    "address1": "72684 Murl Light Apt. 668",
    "address2": "",
    "address3": "",
    "city": "Lake Tedfort",
    "postcode": "29311",
    "state": "01",
    "country": "MYS",
    "sst_number": "W10-1060-26389071",
    "phone": "0125168978",
    "membership_id": "",
    "is_foreign": "false"
  },
  "shipping": {
    "code": "",
    "id_type": "",
    "tin": "",
    "id_number": "",
    "name": "",
    "email": "",
    "address1": "",
    "address2": "",
    "address3": "",
    "city": "",
    "postcode": "",
    "state": "",
    "country": "MYS"
  },
  "annex": {
    "custom_form_number": "",
    "incoterms": "",
    "fta": "",
    "certified_exporter_number": "",
    "custom_k2_number": "",
    "other_charges_description": "",
    "other_charges_amount": ""
  },
  "status": "valid",
  "source": "ERP",
  "type": "01",
  "reference_number": "INV/6990761",
  "invoice_number": "INV/6990761",
  "original_einvoice_ref_number": "",
  "original_einvoice_inv_number": "",
  "po_number": "PO/8555",
  "pos_id": "",
  "created_at": "",
  "issued_at": "2024-10-21",
  "posted_at": "2024-10-23",
  "system_company_name": "",
  "system_company_id": "",
  "outlet_id": "",
  "outlet_code": "HQ",
  "dept_id": "",
  "dept_code": "",
  "job_type": "",
  "created_by": "user@beaconx.com.my",
  "currency_code": "MYR",
  "currency_rate": 1,
  "frequency": "",
  "billing_period_start": "",
  "billing_period_end": "",
  "subtotal": 447.92,
  "discount_rate": 0,
  "discount_amount": 0,
  "total_excl_tax": 447.92,
  "sales_tax_amount": 0,
  "service_tax_amount": 0.00,
  "gst_amount": 0,
  "ttx_amount": 0,
  "hvgt_amount": 0,
  "lvst_amount": 0,
  "exempt_amount": 0,
  "total_tax_amount": 0.0,
  "total_incl_tax": 200.00,
  "service_fee_rate": 0,
  "service_fee_amount": 0,
  "rounding": 0,
  "total_payable_amount": 200.00,
  "payment_mode": "",
  "suppliers_bank_account_number": "",
  "payment_terms": "",
  "prepayment_amount": "",
  "prepayment_datetime": "",
  "prepayment_reference_number": "",
  "bill_reference_number": "",
  "footer_notes": "",
  "so_number": "",
  "do_number": "",
  "template": "",
  "items": [
    {
      "details_tax_exemption": "",
      "tax_exempt_amount": 0,
      "id": "1",
      "classification": "022",
      "product_tariff_code": "",
      "code": "",
      "description": "1-3000",
      "long_description": "",
      "quantity": 1,
      "measurement": "EA",
      "unit_price": 100,
      "subtotal": 100,
      "discount_rate": 0,
      "discount_amount": 0,
      "service_fee_rate": 0,
      "service_fee_amount": 0,
      "total_excl_tax": 100,
      "sales_tax_rate": 0,
      "sales_tax_amount": 0,
      "service_tax_rate": 0.0,
      "service_tax_amount": 0,
      "gst_rate": 0,
      "gst_amount": 0,
      "ttx_rate": 0,
      "ttx_amount": 0,
      "hvgt_rate": 0,
      "hvgt_amount": 0,
      "lvst_rate": 0,
      "lvst_amount": 0,
      "total_incl_tax": 100,
      "country_of_origin": "",
      "total_sales": "",
      "commission_rate": ""
    },
    {
      "details_tax_exemption": "",
      "tax_exempt_amount": 0,
      "id": "2",
      "classification": "022",
      "product_tariff_code": "",
      "code": "",
      "description": "1-4000",
      "long_description": "",
      "quantity": 1,
      "measurement": "EA",
      "unit_price": 100,
      "subtotal": 100,
      "discount_rate": 0,
      "discount_amount": 0,
      "service_fee_rate": 0,
      "service_fee_amount": 0,
      "total_excl_tax": 100,
      "sales_tax_rate": 0,
      "sales_tax_amount": 0,
      "service_tax_rate": 0.0,
      "service_tax_amount": 0,
      "gst_rate": 0,
      "gst_amount": 0,
      "ttx_rate": 0,
      "ttx_amount": 0,
      "hvgt_rate": 0,
      "hvgt_amount": 0,
      "lvst_rate": 0,
      "lvst_amount": 0,
      "total_incl_tax": 100,
      "country_of_origin": "",
      "total_sales": "",
      "commission_rate": ""
    }
  ]
}'

Responses

🟢200Success

application/json

Body

array of:

invoice_number

string

optional

Invoice Number of Document

reference_number

string

optional

Reference Number of Document. Must be unique globally.

pos_id

string

optional

Point of Sale Terminal ID

status

string

optional

Valid - Validated with LHDN. This reflects an actual status in LHDN as Cancelled as well.
Invalid - Failed validation. This reflects an actual status in LHDN as Cancelled as well.
InProgress - Pending status update from LHDN
Submitted - Submitted to LHDN. This reflects an actual status in LHDN as Cancelled as well.
InQueue - Pending to be submitted to LHDN
PendingApproval - On Hold until user manually approves it to be submitted to LHDN
Void - The document is in a void status.
Draft - The document is in a draft mode. (This can only happen if document is created manually via UI and saved as Draft)
Cancelled - The document is in a Cancelled status. This reflects an actual status in LHDN as Cancelled as well.

issued_at

string

optional

Date of document

outlet_code

string

optional

Outlet Code

currency_code

string

optional

currency_rate

integer

optional

supplier

object

optional

tin

string

required

name

string

required

string

required

address

string

required

city

string

required

postcode

string

required

state

string

required

contact

string

required

id_number

string

required

sst_number

string

required

ttx_number

string

required

buyer

object

optional

tin

string

required

name

string

required

string

required

address

string

required

city

string

required

postcode

string

required

state

string

required

contact

string

required

id_number

string

required

sst_number

string

required

membership_id

string

required

items

array [object {10}]

optional

integer

required

quantity

integer

required

subtotal

number

required

unit_price

number

required

description

string

required

measurement

string

required

discount_rate

integer

required

total_excl_tax

number

required

total_incl_tax

number

required

discount_amount

integer

required

quantity

integer

optional

sub_total

number

optional

discount_amount

integer

optional

total_excl_tax

number

optional

service_charge_rate

integer

optional

service_charge_amount

integer

optional

sst_rate

number

optional

sst_amount

number

optional

total_incl_tax

number

optional

rounding

number

optional

total

integer

optional

Examples

Needs AttentionSuccessRejected

{
  "status": "OK",
  "message": "",
  "data": {
    "attention": [
      {
        "reference_number": "10050",
        "payload": {
          "buyer": {
            "code": null,
            "id_type": "BRN",
            "tin": "C61901366810",
            "id_number": "201903007118",
            "name": "MEDHURST, GRIMES AND SIPES SDN. BHD.",
            "email": "kendall.purdy@reilly.net",
            "address1": "72684 Murl Light Apt. 668",
            "address2": null,
            "address3": null,
            "city": "Lake Tedfort",
            "postcode": "29311",
            "state": "01",
            "country": "MYS",
            "sst_number": "W10-1060-26389071",
            "phone": "0125168978",
            "membership_id": null,
            "is_foreign": "false"
          },
          "shipping": {
            "code": null,
            "id_type": null,
            "tin": null,
            "id_number": null,
            "name": null,
            "email": null,
            "address1": null,
            "address2": null,
            "address3": null,
            "city": null,
            "postcode": null,
            "state": null,
            "country": "MYS"
          },
          "annex": {
            "custom_form_number": null,
            "incoterms": null,
            "fta": null,
            "certified_exporter_number": null,
            "custom_k2_number": null,
            "other_charges_description": null,
            "other_charges_amount": null
          },
          "status": "valid",
          "source": "ERP",
          "type": "01",
          "reference_number": "10050",
          "invoice_number": "INV/6990761",
          "original_einvoice_reference_number": null,
          "po_number": "PO/8555",
          "pos_id": null,
          "issued_at": "2024-04-10",
          "outlet_code": "HQ",
          "currency_code": "MYR",
          "currency_rate": null,
          "frequency": null,
          "billing_period_start": null,
          "billing_period_end": null,
          "subtotal": "447.92",
          "discount_rate": "0",
          "discount_amount": "0",
          "total_excl_tax": "447.92",
          "sales_tax_amount": "0",
          "service_tax_amount": "35.83",
          "gst_amount": "0",
          "ttx_amount": "0",
          "hvgt_amount": "0",
          "lvst_amount": "0",
          "total_tax_amount": "35.83",
          "total_incl_tax": "483.75",
          "service_fee_rate": "0",
          "service_fee_amount": "0",
          "rounding": "0",
          "total_payable_amount": "483.75",
          "payment_mode": null,
          "suppliers_bank_account_number": null,
          "payment_terms": null,
          "prepayment_amount": null,
          "prepayment_datetime": null,
          "prepayment_reference_number": null,
          "bill_reference_number": null,
          "items": [
            {
              "id": "1",
              "classification": "022",
              "product_tariff_code": null,
              "code": "123",
              "description": "ullam et ex qui",
              "long_description": "ullam et ex qui ullam et ex qui ullam et ex qui \n ullam et ex qui",
              "quantity": "8",
              "measurement": "UNIT",
              "unit_price": "55.99",
              "subtotal": "447.92",
              "discount_rate": "0",
              "discount_amount": "0",
              "fee_rate": "0.00",
              "fee_amount": "0",
              "charge_rate": "0",
              "charge_amount": "0.00",
              "total_excl_tax": "447.92",
              "sales_tax_rate": "0",
              "sales_tax_amount": "0",
              "service_tax_rate": "0.08",
              "service_tax_amount": "35.83",
              "gst_rate": "0",
              "gst_amount": "0",
              "ttx_rate": "0",
              "ttx_amount": "0",
              "hvgt_rate": "0",
              "hvgt_amount": "0",
              "lvst_rate": "0",
              "lvst_amount": "0",
              "total_incl_tax": "483.75",
              "details_tax_exemption": null,
              "exempt_tax_amount": null,
              "country_of_origin": null
            }
          ]
        },
        "lhdn_uin": "",
        "lhdn_validated_at": "",
        "lhdn_long_id": "",
        "id": "9c0d00a3-3515-4857-8329-9925e58e2703",
        "internal_error_message": "[\"The supplier field is required.\",\"The supplier.id type field is required.\",\"The supplier.tin field is required.\",\"The supplier.id number field is required.\",\"The supplier.name field is required.\",\"The supplier.email field is required.\",\"The supplier.address1 field is required.\"]"
      }
    ],
    "in_queue": [],
    "rejected": []
  }
}