Status and Reconciliation

Every integration must reconcile the final state of each document. Do not treat upload acceptance, an HTTP success code, a submission UID, or an accepted UUID by itself as final validation.

Status by sale GUID

Use the endpoint for the submitted document family and send sale_guid as an HTTP header:

curl --request GET "{api_base_url}/sale/invoice_checkstatus/by_guid" \
  --header "Authorization: Bearer {access_token}" \
  --header "Accept: application/json" \
  --header "sale_guid: {sale_guid}"

Equivalent endpoints exist for all normal and self-billed document families.

The response contains a customer party section and an lhdn section. For self-billed status endpoints, the current response still names the party section customer, but its values come from the stored supplier fields. Integrations must preserve this response contract and map the values according to the document family.

The lhdn section can include:

  • submissionUID;
  • acceptedUUID;
  • longid;
  • submissionOn;
  • outletname;
  • cashierTerminal;
  • saleGuid;
  • saleCode;
  • documentNo;
  • submissionType; and
  • status.

Fields that are not yet assigned can be null.

Status by submission range

Use a range endpoint for recovery, daily reconciliation, or outlet-level monitoring:

curl --request GET "{api_base_url}/sale/invoice_checkstatus/by_submission" \
  --header "Authorization: Bearer {access_token}" \
  --header "Accept: application/json" \
  --header "company_guid: {company_code}" \
  --header "submission_from: 2026-08-26" \
  --header "submission_to: 2026-08-26" \
  --header "outlet_name: TEST OUTLET"

submission_from and submission_to use YYYY-MM-DD, and both boundary dates are included. outlet_name is optional. The company, date range, and any outlet filter are request headers, not query parameters.

The collection is paged at 25 records. Follow the returned paging information until all rows are processed.

Status interpretation

Common values include:

Status Integration action
Pending Submission Stored for later processing. Retain the GUID and check after the configured schedule.
Preparing AECloud is preparing the document. Continue controlled polling.
Submitted Submission has been sent and awaits the final document result.
InProgress Processing is underway. Do not resubmit or void.
Valid Final validation succeeded. Store the accepted UUID and validation information.
Invalid Validation failed. Stop automatic retry of the unchanged payload and investigate the validation result.
Error Processing encountered an error. Classify the error before retrying.
Voided The pre-submission record was voided and will not be submitted.
Cancelled A previously submitted e-Invoice was cancelled.
Non E-Invoice The document was stored with LHDN submission disabled.

Recommended reconciliation model

Maintain a local record containing:

  • source document type and number;
  • company code, outlet, terminal, and shift;
  • QR custom GUID;
  • AECloud sale GUID and sale ID;
  • upload timestamp and request correlation ID;
  • preferred submission mode;
  • last known status and last checked time;
  • submission UID, accepted UUID, and long ID;
  • last error category and message; and
  • void or cancellation outcome.

Poll actively only while a document is expected to change. Once terminal, include it in a periodic audit rather than high-frequency polling.

Identifier meanings

  • Sale GUID identifies the AECloud business record and is the preferred key for AECloud status, void, and cancellation operations.
  • Submission UID identifies the LHDN submission operation.
  • Accepted UUID identifies the individual document accepted for processing by LHDN.
  • Long ID forms part of the validated-document sharing link and must be protected.

Store the identifiers separately; they are not interchangeable.