Billing & Invoices

Manage, create, and void invoices through the external API

The Billing & Invoices API lets external systems submit sales transactions, query bill states, issue credit/debit notes, and void bills in compliance with fiscal regulations.

---

Invoice Lifecycle & State Transitions

Invoices move through distinct financial states from initial submission to final settlement or cancellation:

---

1. List Invoices

Retrieve a list of sales order bills/invoices.

GET /api/v1/external/billing/invoices

Query Parameters

Parameter	Type	Required	Description	Example
page	number	No	Page number	1
limit	number	No	Results per page	10
status	string	No	Filter by invoice status (DRAFT, APPROVED, PAID, VOIDED)	APPROVED

Success Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "e5f67a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
      "billNumber": "INV-2082-0001",
      "totalAmount": 45000,
      "status": "APPROVED"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 10
  }
}

Error Responses

Invalid Date Range (400 Bad Request)

{
  "success": false,
  "status": 400,
  "message": "fromDate must be prior to toDate"
}

---

2. Create Invoice

Create a new sales order bill/invoice.

POST /api/v1/external/billing/invoices

Request Body Example

{
  "customerId": "c1010101-2020-3030-4040-505050505050",
  "paymentMethod": "CASH",
  "items": [
    {
      "productId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "quantity": 2,
      "unitPrice": 1500
    }
  ]
}

Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": "e5f67a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
    "billNumber": "INV-2082-0001",
    "status": "DRAFT",
    "totalAmount": 45000
  }
}

Error Responses

Line Items Validation Error (400 Bad Request)

{
  "success": false,
  "status": 400,
  "message": "Row 1: Items quantity must be a positive number"
}

Customer Not Found (404 Not Found)

{
  "success": false,
  "status": 404,
  "message": "Customer not found"
}

---

3. Void Invoice

Void an existing invoice.

PATCH /api/v1/external/billing/invoices/:id/void

Path Parameters

• id (string, required): The UUID of the invoice.

Request Body

{
  "reason": "Customer returned purchased items"
}

Success Response (200 OK)

{
  "success": true,
  "data": {
    "id": "e5f67a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
    "billNumber": "INV-2082-0001",
    "status": "VOIDED"
  }
}

Error Responses

Invoice Already Voided (400 Bad Request / 409 Conflict)

{
  "success": false,
  "status": 409,
  "message": "Invoice is already voided"
}

Invalid ID Parameter (400 Bad Request)

{
  "success": false,
  "status": 400,
  "message": "Invalid id parameter. Must be a valid UUID."
}

---

4. List Credit Notes

Retrieve credit notes.

GET /api/v1/external/billing/credit-notes

Success Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "c1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "creditNoteNumber": "CN-2082-0001",
      "amount": 5000,
      "status": "APPROVED"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 10
  }
}

Error Responses

Missing or Invalid Client ID (401 Unauthorized)

{
  "success": false,
  "status": 401,
  "message": "Invalid or inactive Client ID or API Key."
}

---

5. Create Credit Note

Create a new credit note.

POST /api/v1/external/billing/credit-notes

Request Body Example

{
  "invoiceId": "e5f67a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
  "amount": 5000,
  "reason": "Price correction credit"
}

Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": "c1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "creditNoteNumber": "CN-2082-0001",
    "amount": 5000,
    "status": "DRAFT"
  }
}

Error Responses

Credit Amount Exceeds Total (400 Bad Request)

{
  "success": false,
  "status": 400,
  "message": "Credit note amount exceeds invoice balance"
}

---

6. List Debit Notes

Retrieve debit notes.

GET /api/v1/external/billing/debit-notes

Success Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "d1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "debitNoteNumber": "DN-2082-0001",
      "amount": 4200,
      "status": "APPROVED"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 10
  }
}

---

7. Create Debit Note

Create a new debit note.

POST /api/v1/external/billing/debit-notes

Request Body Example

{
  "invoiceId": "e5f67a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
  "amount": 4200,
  "reason": "Additional delivery charge adjustment"
}

Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": "d1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "debitNoteNumber": "DN-2082-0001",
    "amount": 4200,
    "status": "DRAFT"
  }
}

Error Responses

Invoice Not Found (404 Not Found)

{
  "success": false,
  "status": 404,
  "message": "Referenced invoice not found"
}