> For the complete documentation index, see [llms.txt](https://amast-einvoice.gitbook.io/amast-einvoice-sass/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://amast-einvoice.gitbook.io/amast-einvoice-sass/core-concepts.md).

# Core Concepts

## 1  einvoice submission API call = 1 submission batch

Each `POST /v1/einvoice/submit` creates exactly **one** `submissionBatchId`. Each submission batch must not exceed than 100 documents.\
\
Our platform accepts both document type Invoice (IV) + Credit Note (CN) in 1 batch. \
\
For CNs tied to IVs you are submitting now, submit IV batch first → wait IV to Valid → submit CN (in separate batches), unless the parent invoice already has an LHDN UUID you can put on `relatedInvoice`. Refer [Credit Note Submission Example](/amast-einvoice-sass/api/list-of-api/submit-document-api.md#non-consolidated-credit-note)

{% hint style="info" %}
It is **recommended** to submit the IV batch first. Only submit a CN after its associated IV has been confirmed as **Valid** to avoid CN submission errors.
{% endhint %}

## Submission types:

## Consolidated vs Non-Consolidated

<table><thead><tr><th width="193"></th><th width="262">Non-consolidated</th><th width="291">Consolidated</th></tr></thead><tbody><tr><td><strong>Typical use</strong></td><td>On the spot B2B/B2C using legitimate buyer TIN detail on eInvoice</td><td>Retail-style where einvoice submission likely to happen end of month.</td></tr><tr><td><strong>Buyer on LHDN</strong></td><td>Your <code>recipient</code> data</td><td>Fixed by LHDN (See below section)</td></tr><tr><td><strong><code>recipient</code> in API</strong></td><td>Required </td><td>Not required, our platform handled in backend.</td></tr></tbody></table>

### Consolidated buyer profile details (fixed by LHDN)

| Field                   | Default Value  |
| ----------------------- | -------------- |
| Buyer name              | General Public |
| Buyer TIN               | EI00000000010  |
| Buyer ID type / number  | NA             |
| Address / contact / SST | NA             |

{% hint style="info" %}
**Important:** While our platform automatically applies LHDN's default values where applicable (i.e Consolidate Submission), the user remains responsible for the accuracy of the submitted data and for maintaining all underlying POS, sales, and supporting records required for audit and compliance purposes.
{% endhint %}

## Idempotency

Header (required on submit and cancel):

```
idempotency-key: your-unique-string   (max 255 chars)
```

| Rule                          | Behaviour                                    |
| ----------------------------- | -------------------------------------------- |
| Same key + **same** body      | Safe retry; may return cached `200` response |
| Same key + **different** body | `409` hash mismatch                          |
| Concurrent duplicate key      | `409` already being processed                |

Generate a **new** key for each logical submit. Reuse only when retrying the **exact** same payload after timeout.

## Credits (billing)

* **Submit:** 1 prepaid credit per document in the batch (checked before queueing).
* **Cancel:** 1 credit per cancel request.
* **`402`:** Insufficient credits — top up in dashboard, then retry with same idempotency key if appropriate.
* Credits typically expire **12 months** from purchase (confirm on your plan/invoice).

{% hint style="info" %}
Credit deduction applies to both Production and Sandbox API Key
{% endhint %}

## Duplicate protection (platform scope)

Our platform blocks resubmission when the same tenant attempts to submit a document with the same `documentType` and `referenceId`, under the following conditions:

* **Platform status:** Queued, Processing, or Submitted (internal), or
* **LHDN status:** Submitted or Valid

We do not perform duplicate checks against MyInvois or other external integrators.

Resubmission is allowed only when the previous LHDN status is **Invalid** or **Cancelled**, in accordance with platform rules.

## `referenceId`

Your stable business identifier (invoice number, credit note number). Used for duplicate detection and LHDN billing reference.\
\
Example: \
IV11122026-001\
CN25122026-005

## Credit notes and its parent/associated Invoices

Credit notes require:

```json
"relatedInvoice": {
  "referenceId": "PARENT-INV-NUMBER",
  "lhdnUuid": "uuid-from-lhdn-mytax"
}
```

* Invoice issued **via our Platform** and Valid: you may omit `lhdnUuid`; we look it up by `referenceId`.
* Invoice issued **elsewhere other than our Platform**: you **must** pass `lhdnUuid` from MyTax LHDN. You may poll Submission Status API to get the MyTax LHDN UUID on individual document in a batch.&#x20;

Multiple credit notes against one associated Invoice are allowed if each credit note has a **unique** `referenceId`.<br>

## Transaction ID

Transaction ID is mainly used for internal dashboard tracking and Transaction listing. Below are the differences between `transactionId`, `submissionBatchId`, and `documentId`. You may encounter these terms across our platform.

| ID                  | Scope                               | Meaning                                                                     |
| ------------------- | ----------------------------------- | --------------------------------------------------------------------------- |
| `transactionId`     | One per document per submit attempt | Row in `transactions` for that doc in that API call                         |
| `submissionBatchId` | One per submit request              | Same for all docs in one `POST /v1/einvoice/submit`                         |
| `documentId`        | One per logical document            | Stable for `documentType` + `referenceId` (resubmit may reuse same doc row) |

Example: One batch with 2 invoices → 1 `submissionBatchId`, 2 `transactionId`s, 2 `documentId`s.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://amast-einvoice.gitbook.io/amast-einvoice-sass/core-concepts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.