BizCARE MyInvois
API Reference

Adjustment Notes API

Complete API reference for managing adjustment notes (credit notes and debit notes)

Adjustment Notes API

This section covers all adjustment note-related endpoints for creating, updating, retrieving, and managing adjustment notes (credit notes and debit notes) in the Malaysian e-invoicing system.

Authentication

All endpoints require authentication via API key:

X-API-Key: your-api-key-here

Base URL

/api

Get All Adjustment Notes

Retrieve a paginated list of all adjustment notes.

Endpoint

GET /api/adjustment-notes

Headers

X-API-Key: your-api-key-here

Query Parameters

Standard pagination parameters are supported.

Response Example

{
  "meta": {
    "total": 2,
    "per_page": 10,
    "current_page": 1,
    "last_page": 1,
    "first_page": 1,
    "first_page_url": "/?page=1",
    "last_page_url": "/?page=1",
    "next_page_url": null,
    "previous_page_url": null
  },
  "data": [
    {
      "id": 26,
      "company_id": 2,
      "user_id": 1,
      "invoice_id": 54,
      "consolidated_invoice_id": null,
      "code": "2",
      "type": "CREDIT_NOTE",
      "line_items": [
        {
          "id": "1",
          "unit": {
            "code": "EA",
            "count": 1,
            "price": 10
          },
          "taxAmount": 0,
          "taxDetails": [
            {
              "taxRate": {
                "percentage": 0
              },
              "taxType": "06",
              "taxAmount": 0,
              "taxableAmount": 10
            }
          ],
          "description": "correction",
          "originCountry": "MYS",
          "classifications": ["022"]
        }
      ],
      "issue_date": "2025-08-26T08:48:21.713+00:00",
      "created_at": "2025-08-26T08:48:21.713+00:00",
      "updated_at": "2025-08-26T08:48:21.713+00:00",
      "invoice_code_with_prefix_and_digits": "25CN-00002",
      "consolidated_invoice": null,
      "company": {
        "id": 2,
        "name": "Gaincue Retail",
        "tin_code": "IG12345678901"
      },
      "submitted_documents": [
        {
          "id": 41,
          "document_submission_id": 46,
          "adjustment_note_id": 26,
          "code": "25CN-00002",
          "uuid": "QF13HNCSXRGMG4GD3YCCYJ3K10",
          "status": "Valid",
          "fail_reason": null,
          "fail_details": null
        }
      ]
    }
  ]
}

Get Specific Adjustment Note

Retrieve details of a specific adjustment note.

Endpoint

GET /api/adjustment-notes/:id

Headers

X-API-Key: your-api-key-here

Path Parameters

ParameterTypeDescription
idintegerAdjustment note ID

Response

Returns the same structure as individual adjustment note objects in the "Get All Adjustment Notes" response.

Update Adjustment Note

Update an existing adjustment note.

Endpoint

PUT /api/adjustment-notes/:id

Headers

X-API-Key: your-api-key-here
Content-Type: application/json

Path Parameters

ParameterTypeDescription
idintegerAdjustment note ID

Request Body

Similar structure to the adjustment note creation request. You can update any of the adjustment note fields.

Delete Adjustment Note

Delete a specific adjustment note.

Endpoint

DELETE /api/adjustment-notes/:id

Headers

X-API-Key: your-api-key-here

Path Parameters

ParameterTypeDescription
idintegerAdjustment note ID

Response Examples

Success (200)

{
  "message": "Adjustment Note deleted successfully"
}

Error - Already Submitted (403)

{
  "success": false,
  "message": "A submitted adjustment note cannot be deleted, please cancel first and try again. A submitted document can only be cancelled within 72 hours after submission"
}

Submit Adjustment Note to MyInvois

Submit an adjustment note to the MyInvois system for validation and processing.

Endpoint

POST /api/adjustment-notes/:id/submit-to-myinvois

Headers

X-API-Key: your-api-key-here

Path Parameters

ParameterTypeDescription
idintegerAdjustment note ID

Request Body

Empty JSON object: {}

Response Examples

Success (200)

{
  "success": true,
  "message": "Submitted successfully"
}

Error - Invalid Status (400)

{
  "success": false,
  "message": "Only valid status invoice can be submitted"
}

Cancel Latest Submitted Adjustment Note

Cancel the latest submitted document for an adjustment note (must be within 72 hours of submission).

Endpoint

POST /api/adjustment-notes/:id/cancel-latest-adjustment-note-submitted

Headers

X-API-Key: your-api-key-here

Path Parameters

ParameterTypeDescription
idintegerAdjustment note ID

Response Examples

Success (200)

{
  "success": true,
  "message": "Cancelled submitted document successfully"
}

Error - Not Found (400)

{
  "success": false,
  "message": "Latest adjustment note not found"
}

Get Submitted Documents

Retrieve all submitted documents associated with an adjustment note.

Endpoint

GET /api/adjustment-notes/:id/submitted-documents

Headers

X-API-Key: your-api-key-here

Path Parameters

ParameterTypeDescription
idintegerAdjustment note ID

Response Example

{
  "meta": {
    "total": 3,
    "per_page": 10,
    "current_page": 1,
    "last_page": 1,
    "first_page": 1,
    "first_page_url": "/?page=1",
    "last_page_url": "/?page=1",
    "next_page_url": null,
    "previous_page_url": null
  },
  "data": [
    {
      "id": 5,
      "document_submission_id": 5,
      "adjustment_note_id": 1,
      "invoice_id": 3,
      "consolidated_invoice_id": null,
      "company_id": 2,
      "user_id": 4,
      "code": "25A-CN-00001",
      "uuid": "NK8G8888FQ68M2H0G42RQM3K10",
      "status": "Valid",
      "fail_reason": null,
      "fail_details": null,
      "document_details": {
        "Invoice": {
          "ID": "25A-CN-00001",
          "UUID": "NK8G8888FQ68M2H0G42RQM3K10",
          "InvoiceTypeCode": {
            "listVersionID": "1.0",
            "value": "02"
          },
          "DocumentCurrencyCode": "MYR",
          "InvoiceNumber": "25A-CN-00001"
        }
      },
      "type": "CREDIT_NOTE",
      "cancel_reason": null,
      "long_id": "2KYQ0XBVYF4QJCE0G42RQM3K10JN32SY1756263876",
      "created_at": "2025-08-27T03:04:36.755+00:00",
      "updated_at": "2025-08-27T03:04:46.163+00:00"
    }
  ]
}

Get Specific Submitted Document

Retrieve details of a specific submitted document for an adjustment note.

Endpoint

GET /api/adjustment-notes/:id/submitted-documents/:submitted_document_id

Headers

X-API-Key: your-api-key-here

Path Parameters

ParameterTypeDescription
idintegerAdjustment note ID
submitted_document_idintegerSubmitted document ID

Response Examples

Success (200)

Returns the specific submitted document details (similar structure to individual items in the previous endpoint).

Error (404)

{
  "message": "Submitted document not found"
}

Create Adjustment Note for Invoice

Create an adjustment note for a specific invoice.

Endpoint

POST /api/invoices/:id/adjustment-note

Headers

X-API-Key: your-api-key-here
Content-Type: application/json

Path Parameters

ParameterTypeDescription
idintegerInvoice ID

Request Body

FieldTypeRequiredDescription
targetInvoiceTypestringYesType of target invoice: INVOICE
typestringYesAdjustment note type: CREDIT_NOTE, DEBIT_NOTE
adjustmentNoteCodenumberYesUnique adjustment note code
adjustmentNoteIssueDatestringYesIssue date (ISO 8601 format)
lineItemsarrayYesArray of adjustment line items

Request Example

{
  "targetInvoiceType": "INVOICE",
  "type": "CREDIT_NOTE",
  "adjustmentNoteCode": 123,
  "adjustmentNoteIssueDate": "2023-08-01T00:00:00.000Z",
  "lineItems": [
    {
      "id": "item-1",
      "classifications": ["001"],
      "description": "Adjustment for invoice item",
      "unit": {
        "price": 100,
        "count": 2,
        "code": "EA"
      },
      "taxDetails": [
        {
          "taxType": "06",
          "taxRate": {
            "percentage": 6
          }
        }
      ],
      "taxExemption": {
        "taxableAmount": 50,
        "reason": "Partial tax exemption"
      },
      "allowanceCharges": [
        {
          "amount": 10,
          "reason": "Discount for early payment",
          "isCharge": false
        }
      ],
      "originCountry": "MYS"
    }
  ]
}

Response Examples

Success (200)

{
  "success": true,
  "message": "Successfully created adjustment note"
}

Error - Invoice Waiting Validation (403)

{
  "success": false,
  "message": "The invoice has been submitted but not yet being validated by LHDN or latest submission result status is not valid."
}

Error - Invoice Not Submitted (403)

{
  "success": false,
  "message": "The invoice has not been submitted."
}

Create Adjustment Note for Consolidated Invoice

Create an adjustment note for a specific consolidated invoice.

Endpoint

POST /api/consolidated-invoices/:id/adjustment-note

Headers

X-API-Key: your-api-key-here
Content-Type: application/json

Path Parameters

ParameterTypeDescription
idintegerConsolidated invoice ID

Request Body

Same structure as creating an adjustment note for a regular invoice.

Adjustment Note Data Structure

Main Adjustment Note Object

FieldTypeDescription
idnumberUnique adjustment note identifier
company_idnumberAssociated company ID
user_idnumberAssociated user ID
invoice_idnumber|nullAssociated invoice ID
consolidated_invoice_idnumber|nullAssociated consolidated invoice ID
codestringAdjustment note code
typestringType: CREDIT_NOTE or DEBIT_NOTE
line_itemsarrayArray of line items
issue_datestringIssue date (ISO 8601 format)
created_atstringCreation timestamp
updated_atstringLast update timestamp
invoice_code_with_prefix_and_digitsstringFull invoice code with prefix
consolidated_invoiceobject|nullAssociated consolidated invoice
companyobjectAssociated company information
submitted_documentsarrayArray of submitted documents

Line Item Object

FieldTypeDescription
idstringLine item identifier
unitobjectUnit details
unit.codestringUnit code (e.g., "EA")
unit.countnumberQuantity
unit.pricenumberUnit price
taxAmountnumberTotal tax amount
taxDetailsarrayArray of tax details
descriptionstringItem description
originCountrystringCountry of origin (ISO 3166-1 alpha-3)
classificationsarrayArray of classification codes

Submitted Document Object

FieldTypeDescription
idnumberSubmitted document ID
document_submission_idnumberDocument submission ID
adjustment_note_idnumberAssociated adjustment note ID
codestringDocument code
uuidstringUUID from MyInvois
statusstringDocument status
fail_reasonstring|nullFailure reason if applicable
fail_detailsstring|nullFailure details if applicable
document_detailsobjectFull UBL XML document structure
typestringDocument type
cancel_reasonstring|nullCancellation reason if applicable
long_idstringLong identifier from MyInvois
created_atstringCreation timestamp
updated_atstringLast update timestamp

Common Error Codes

Status CodeDescription
200OK - Request successful
400Bad Request - Invalid request data or operation not allowed
401Unauthorized - Invalid or missing API key
403Forbidden - Operation not allowed (e.g., trying to delete submitted note)
404Not Found - Resource not found
422Unprocessable Entity - Validation errors

Important Notes

  1. Adjustment Note Types:

    • CREDIT_NOTE: Used to reduce the amount of an invoice (e.g., refunds, discounts)
    • DEBIT_NOTE: Used to increase the amount of an invoice (e.g., additional charges)

  2. 72-Hour Rule: Submitted adjustment notes can only be cancelled within 72 hours of submission to MyInvois

  3. Deletion Restrictions: Adjustment notes that have been submitted to MyInvois cannot be deleted; they must be cancelled first

  4. Parent Document Requirement: Adjustment notes must be linked to either an invoice or consolidated invoice

  5. Status Dependencies:

    • The parent invoice/consolidated invoice must be in a valid state before creating adjustment notes
    • Only adjustment notes with valid status can be submitted to MyInvois

  6. Code Uniqueness: Adjustment note codes must be unique within the company for each calendar year

  7. Date Format: All dates must be in ISO 8601 format (e.g., "2025-08-01T00:00:00.000Z")

  8. Tax Types: Use Malaysian tax type codes (e.g., "01" for SST, "06" for Not Applicable)

  9. Country Codes: Use "MYS" for Malaysia (ISO 3166-1 alpha-3)

Validations API

Complete API reference for validation services in the E-Invoice system

Consolidated Invoices API

Complete API reference for managing consolidated invoices in the E-Invoice system