> 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/api/list-of-api/submit-document-api.md).

# Submit Document API

Queue one or more e-Invoice documents in a single batch. 

{% hint style="info" %}
Requires prepaid credits (1 credit per document submitted). \
\
Credits are deducted upon a successful call to our API, regardless of the submission outcome. This includes cases where the document is accepted or rejected due to LHDN internal validation failures (e.g., invalid TIN combinations or other validation errors).

Examples:

* 1 document in a single `POST /v1/einvoice/submit` request = 1 credit
* 50 documents in a single `POST /v1/einvoice/submit` request = 50 credits
* 100 documents in a single `POST /v1/einvoice/submit` request = 100 credits
  {% endhint %}

```bash
POST /api/v1/einvoice/submit
```

## Headers

<table><thead><tr><th width="266.77783203125">Header</th><th width="135.5555419921875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>X-API-Key</code> or <code>Authorization: Bearer</code></td><td>Yes</td><td>API key</td></tr><tr><td><code>Content-Type</code></td><td>Yes</td><td><code>application/json</code></td></tr><tr><td><code>idempotency-key</code></td><td>Yes</td><td>Unique per logical submit (max 255 chars)</td></tr></tbody></table>

## Limits

* **Max 100 documents** per request.
* Larger runs: multiple requests, each with its own `idempotency-key`.

## Request body

### Envelope Payload

| Form                                                                                              | Note                                                              |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| <p><code>{ "submission\_type": "...", "documents": \[ {...}, {...} ]</code><br><code>}</code></p> | Required `submission_type` : `consolidated` or `non-consolidated` |

### Documents object

<table><thead><tr><th width="190.22222900390625">Field</th><th width="209.22216796875">Required</th><th width="385.802001953125">Description</th></tr></thead><tbody><tr><td><code>documentType</code></td><td>Yes</td><td><code>invoice</code>, <code>credit_note</code></td></tr><tr><td><code>referenceId</code></td><td>Yes</td><td>Your business document number <br>(invoice/CN no.)</td></tr><tr><td><code>document_date</code> or <code>documentDate</code></td><td>Yes</td><td><code>YYYY-MM-DD</code></td></tr><tr><td><code>recipient</code></td><td>Non-consolidated: Yes<br>Consolidated: No </td><td>Buyer details (see <a href="broken://pages/6d5dc4bfe7bc10d56e0ca7108996ed52e7bb8545">Request schema</a>)</td></tr><tr><td><code>totalDiscountAmount</code></td><td>Optional</td><td>Header level discount, not sum of line level discount</td></tr><tr><td><code>totalRoundingAmount</code></td><td>Optional</td><td>Header level rounding</td></tr><tr><td><code>recipient</code></td><td>Consolidated: No</td><td>Ignored if sent</td></tr><tr><td><code>lineItems</code></td><td>Yes</td><td>Array of line objects, refer next section for details</td></tr><tr><td><code>relatedInvoice</code></td><td>Credit note: Yes</td><td>Parent invoice reference</td></tr></tbody></table>

{% hint style="info" %}
To simplify your e-Invoice submission process via our Platform, some total values (e.g., **totalPayableAmount**, **totalIncludingTax**, and **totalExcludingTax**) are automatically calculated by our backend. You only need to provide accurate line-level data in the simplified JSON.
{% endhint %}

### Line Items object

| Field         | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| `description` | string | Line description                                |
| `quantity`    | number | Quantity                                        |
| `unitPrice`   | number | Unit price                                      |
| `lineTotal`   | number | Line extension amount                           |
| `taxAmount`   | number | Tax amount for line                             |
| `discount`    | number | Line level discount in currency, not percentage |

## Examples

{% tabs %}
{% tab title="Non-consolidated Invoice" %}

```bash
curl -X POST "https://teinvoice.amastsales-sandbox.com/api/v1/einvoice/submit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: <change_to_unique_number>" \
  -d '{
  "submission_type": "non-consolidated",
  "documents": [
    {
      "documentType": "invoice",
      "referenceId": "INV-1001",
      "document_date": "2026-04-06",
      "recipient": {
        "name": "Buyer Sdn Bhd",
        "addressLine1": "1 Jalan Contoh",
        "addressLine2": "Suite 2",
        "postcode": "50000",
        "state": "kuala_lumpur",
        "city": "KL",

        ######################### Enable below If a buyer is a company
        // "tin": "C98765432101",    
        // "brn": "202001234567",      
        // "entity_type": "company"

        ######################### Enable belowIf a buyer is a sole proprietor
        // "tin": "IG1234567890",   
        // "nric": "920203-02-5188",     
        // "entity_type": "individual"  
      },
      "totalDiscountAmount": 5,
      "totalRoundingAmount": -0.03,
      "lineItems": [
        { 
          "description": "Air Mineral", 
          "quantity": 2, 
          "unitPrice": 30.03, 
          "lineTotal": 30.03, 
          "discount": 10, 
          "taxAmount": 1 
        }
      ]
    }
  ]
}'
```

{% endtab %}

{% tab title="Consolidated Invoice" %}

```bash
curl -X POST "https://teinvoice.amastsales-sandbox.com/api/v1/einvoice/submit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: <change_to_unique_number>" \
  -d '{
  "submission_type": "consolidated",
  "documents": [
    {
      "documentType": "invoice",
      "referenceId": "CS-INV-0001",
      "document_date": "2026-04-06",
      "totalDiscountAmount": 5,
      "totalRoundingAmount": -0.03,
      "lineItems": [
        { 
          "description": "Air Mineral", 
          "quantity": 2, 
          "unitPrice": 30.03, 
          "lineTotal": 30.03, 
          "discount": 10, 
          "taxAmount": 1 
        }
      ]
    }
  ]
}'
```

{% endtab %}

{% tab title="Non-consolidated Credit Note" %}

```bash
curl -X POST "https://teinvoice.amastsales-sandbox.com/api/v1/einvoice/submit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: <change_to_unique_number>" \
  -d '{
  "submission_type": "non-consolidated",
  "documents": [
    {
      "documentType": "credit_note",
      "referenceId": "CN-1001",
      "document_date": "2026-06-01",
      "relatedInvoice": {
        "referenceId": "INV-1001",
        "lhdnUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      "recipient": {
        "name": "Buyer Sdn Bhd",
        "addressLine1": "1 Jalan Contoh",
        "addressLine2": "Suite 2",
        "postcode": "50000",
        "state": "kuala_lumpur",
        "city": "KL",

        ######################### Enable below If a buyer is a company
        // "tin": "C98765432101",    
        // "brn": "202001234567",      
        // "entity_type": "company"

        ######################### Enable belowIf a buyer is a sole proprietor
        // "tin": "IG1234567890",   
        // "nric": "920203-02-5188",     
        // "entity_type": "individual"  
      },
      "totalDiscountAmount": 5,
      "totalRoundingAmount": -0.03,
      "lineItems": [
        { 
          "description": "Air Mineral", 
          "quantity": 2, 
          "unitPrice": 30.03, 
          "lineTotal": 30.03, 
          "discount": 10, 
          "taxAmount": 1 
        }
      ]
    }
  ]
}'
```

{% endtab %}

{% tab title="Consolidated Credit Note" %}

```bash
curl -X POST "https://teinvoice.amastsales-sandbox.com/api/v1/einvoice/submit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: <change_to_unique_number>" \
  -d '{
  "submission_type": "consolidated",
  "documents": [
    {
      "documentType": "credit_note",
      "referenceId": "CS-CN-0001",
      "document_date": "2026-06-01",
      "relatedInvoice": {
        "referenceId": "CS-INV-0001",
        "lhdnUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      "totalDiscountAmount": 5,
      "totalRoundingAmount": -0.03,
      "lineItems": [
        { 
          "description": "Air Mineral", 
          "quantity": 2, 
          "unitPrice": 30.03, 
          "lineTotal": 30.03, 
          "discount": 10, 
          "taxAmount": 1 
        }
      ]
    }
  ]
}'
```

{% endtab %}
{% endtabs %}

See [State reference](/amast-einvoice-sass/appendix/malaysia-states-slug.md)

## Responses

### 200 OK

```json
{  
     "submissionBatchId":"9170afbe-1736-4160-9fef-9a34235585bb",
     "documents":[
        {
          "documentId":"52595643-30bb-44d4-b01a-ca420e49023e",
          "documentType":"invoice",
          "referenceId":"INV111-SANDBOXTEST-003"
        },
        { 
          "documentId":"b3a93ac8-d4e0-4d84-9350-d32c71ef040d",
          "documentType":"invoice",
          "referenceId":"INV111-SANDBOXTEST-004"
        }
      ]
}
```

### 400 Bad Request

```json
{
  "message": "first error string",
  "errors": ["error 1", "error 2"]
}
```

Missing idempotency:

```json
{ "message": "Header idempotency-key is required (max 255 characters)" }
```

### 402 Payment Required

```json
{
  "message": "Insufficient prepaid API credits: need 3 credit(s) for 3 document(s), 1 remaining, short by 2",
  "requiredCredits": 3,
  "remainingCredits": 1,
  "shortBy": 2,
  "documentCount": 3
}
```

### 409 Conflict

Idempotency:

```json
{ "message": "Idempotency key was already used with a different request body" }
```

```json
{ "message": "Duplicate idempotent request: same key is already being processed" }
```

Duplicate document:

```json
{
  "message": "Document already exists and cannot be resubmitted",
  "documentType": "invoice",
  "referenceId": "INV-123",
  "submissionStatus": "Submitted",
  "lhdnStatus": "Valid"
}
```

### 500 Internal Server Error

```json
{ "message": "Internal Server Error" }
```

See [Error reference](/amast-einvoice-sass/error-reference.md).


---

# 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/api/list-of-api/submit-document-api.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.