Payload Reference

Submission endpoints accept one AECloud business document as the raw JSON body. Property names are case-sensitive.

Top-level objects

Object	Required	Purpose
`aec`	Yes	Merchant routing, outlet, receipt QR identifier, and scheduling instructions.
`sales`	Yes	Document number, date, currency, totals, and LHDN-submission intent.
`taxes`	Yes	Tax totals grouped by tax type. At least one entry is required.
`customer`	For non-consolidated sale documents	Buyer identity, address, and contact information.
`supplier`	For non-consolidated self-billed documents	Supplier identity, address, business classification, and contact information.
`shipping`	No	Delivery-party details. If included, its core identity and address fields must be complete.
`originalInvoices`	Adjustment documents	References the original invoice for credit, debit, and refund notes.
`items`	Yes	One or more document lines.

`aec` object

Property	Required	Notes
`companyCode`	Yes	Merchant GUID supplied by AECloud.
`outletName`	Yes	Exact outlet name. Case-insensitive matching is used for existing sales records, but consistent spelling is essential.
`cashierTerminal`	Yes	Terminal or source-system identifier.
`shiftCode`	Yes	Shift identifier. It remains required even though existing-record matching does not use it.
`qr_custom_guid`	Yes	Unique receipt/customer-portal identifier, up to 64 characters. Reuse it only for the same business document.
`preferred_submission_on`	Yes	One of `now`, `setting`, or `conso`.

Submission timing values mean:

now — submit immediately when sales.lhdnSubmission is yes;
setting — store the document for the merchant's next configured individual submission time; and
conso — schedule it for the merchant's configured consolidated-submission day.

Use conso only for a workflow that the merchant and AECloud have approved as consolidatable.

`sales` object

Property	Required	Notes
`documentNo`	Yes	Stable source-system document number.
`lhdnSubmission`	Yes	The implemented processing is case-insensitive for `yes` and `no`; for example, `YES` and `yes` are treated alike. Use one consistent form across the integration. `yes` creates the LHDN-submission path; `no` stores the record as non-e-Invoice.
`saleType`	Yes	Business sale type agreed for the integration. The current validator requires a non-empty value but does not publish a universal value list.
`documentDate`	Yes	UTC ISO timestamp in the implemented form `YYYY-MM-DDTHH:mm:ss.SSSZ`, for example `2026-08-26T02:30:00.000Z`.
`currencyCode`	Yes	Code returned by `/lhdn/currency_code`, such as `MYR`.
`currencyRate`	Yes	Numeric value.
`totalExcludingTax`	Yes	Numeric document total before tax.
`totalIncludingTax`	Yes	Numeric document total including tax.
`grandTotal`	Yes	Numeric payable total.
`totalTaxAmount`	Yes	Numeric total tax.
`totalDiscount`	No	Total allowance or discount; defaults to zero during conversion.
`additionalCharges`	No	Document-level charge; defaults to zero.
`roundingAdjustment`	No	Payable rounding adjustment; defaults to zero.

Numbers may be represented as JSON strings in the accepted business payload, but they must contain numeric text. Use a consistent decimal representation and reconcile all totals before sending.

`taxes` entries

Each entry requires:

taxType;
taxAmountPerTaxType.

When an exemption reason is required, the current implemented property name is taxExamptedReason. Preserve this exact spelling until AECloud announces a contract change.

Buyer or supplier object

The required sale-document customer fields are:

name, contact, tin, idType, idNum;
addressLine1, city, state, country.

Optional stored fields include email, sstRegNum, addressLine2, addressLine3, and postcode. The current normal sale credit-note and debit-note validators additionally require postcode; the normal invoice and refund-note validators do not currently enforce it. Supplying a valid postcode whenever applicable keeps the party address complete.

The self-billed supplier object uses the same identity, contact, and address pattern and additionally requires msicCode and msicDescription. Optional stored fields include supplier email, SST registration, additional address lines, and postcode.

Use supported identification values such as NRIC, PASSPORT, BRN, or ARMY as applicable. Validate real taxpayer details rather than copying sample values.

`shipping` object

When shipping is present, provide all of these fields:

name, tin, idType, idNum;
addressLine1, city, state, country.

Do not send a partially populated shipping object. Omit it when the document has no separate shipping party.

`items` entries

Each item requires:

itemNo;
classification;
description;
quantity;
unitPrice;
subTotal;
itemTaxType;
taxRate;
itemTaxAmount; and
itemTotalExcludingTax.

Supported optional line values include uom and itemDiscount. When needed, the currently implemented exemption property is itemTaxExamptedReason; preserve the spelling exactly.

Retrieve classification, tax, and unit codes from the AECloud reference endpoints instead of hard-coding an unmaintained list.

Canonical sale-invoice example

All organizations and identifiers below are fictitious. Replace the saleType value with the value approved for your integration.

{
  "aec": {
    "companyCode": "00112233445566778899AABBCCDDEEFF",
    "outletName": "TEST OUTLET",
    "cashierTerminal": "POS-01",
    "shiftCode": "SHIFT-001",
    "qr_custom_guid": "11223344556677889900AABBCCDDEEFF",
    "preferred_submission_on": "now"
  },
  "sales": {
    "documentNo": "TEST-INV-20260826-0001",
    "lhdnSubmission": "yes",
    "saleType": "{approved_sale_type}",
    "documentDate": "2026-08-26T02:30:00.000Z",
    "currencyCode": "MYR",
    "currencyRate": "1",
    "totalDiscount": "0.00",
    "additionalCharges": "0.00",
    "roundingAdjustment": "0.00",
    "totalExcludingTax": "100.00",
    "totalIncludingTax": "100.00",
    "grandTotal": "100.00",
    "totalTaxAmount": "0.00"
  },
  "taxes": [
    {
      "taxType": "{applicable_tax_type}",
      "taxAmountPerTaxType": "0.00"
    }
  ],
  "customer": {
    "name": "TEST BUYER SDN BHD",
    "contact": "+60300000000",
    "tin": "{validated_buyer_tin}",
    "idType": "BRN",
    "idNum": "{validated_buyer_brn}",
    "email": "buyer@example.com",
    "addressLine1": "1 TEST STREET",
    "city": "KUALA LUMPUR",
    "state": "{applicable_state_code}",
    "postcode": "50000",
    "country": "{applicable_country_code}"
  },
  "items": [
    {
      "itemNo": "1",
      "classification": "{applicable_classification_code}",
      "description": "TEST SERVICE",
      "quantity": "1",
      "uom": "{applicable_unit_code}",
      "unitPrice": "100.00",
      "subTotal": "100.00",
      "itemDiscount": "0.00",
      "itemTaxType": "{applicable_tax_type}",
      "taxRate": "0.00",
      "itemTaxAmount": "0.00",
      "itemTotalExcludingTax": "100.00"
    }
  ]
}

JSON containing {placeholder} values is not ready for submission. Replace every placeholder with validated environment and business data first.

Payload Reference

Top-level objects

aec object

sales object

taxes entries