> ## Documentation Index
> Fetch the complete documentation index at: https://help.kuverbooks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```mermaid actions={false} theme={null}
stateDiagram-v2
    [*] --> DRAFT: POST /api/v1/external/billing/invoices
    DRAFT --> APPROVED: Payment Submitted / Invoice Finalized
    APPROVED --> PAID: Full Payment Received
    APPROVED --> VOIDED: PATCH /billing/invoices/:id/void
    DRAFT --> VOIDED: PATCH /billing/invoices/:id/void
    PAID --> [*]
    VOIDED --> [*]
```

***

### 1. List Invoices

Retrieve a list of sales order bills/invoices.

```http theme={null}
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`)

```json theme={null}
{
  "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`)

```json theme={null}
{
  "success": false,
  "status": 400,
  "message": "fromDate must be prior to toDate"
}
```

***

### 2. Create Invoice

Create a new sales order bill/invoice.

```http theme={null}
POST /api/v1/external/billing/invoices
```

#### Request Body Example

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

#### Success Response (`201 Created`)

```json theme={null}
{
  "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`)

```json theme={null}
{
  "success": false,
  "status": 400,
  "message": "Row 1: Items quantity must be a positive number"
}
```

##### Customer Not Found (`404 Not Found`)

```json theme={null}
{
  "success": false,
  "status": 404,
  "message": "Customer not found"
}
```

***

### 3. Void Invoice

Void an existing invoice.

```http theme={null}
PATCH /api/v1/external/billing/invoices/:id/void
```

#### Path Parameters

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

#### Request Body

```json theme={null}
{
  "reason": "Customer returned purchased items"
}
```

#### Success Response (`200 OK`)

```json theme={null}
{
  "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`)

```json theme={null}
{
  "success": false,
  "status": 409,
  "message": "Invoice is already voided"
}
```

##### Invalid ID Parameter (`400 Bad Request`)

```json theme={null}
{
  "success": false,
  "status": 400,
  "message": "Invalid id parameter. Must be a valid UUID."
}
```

***

### 4. List Credit Notes

Retrieve credit notes.

```http theme={null}
GET /api/v1/external/billing/credit-notes
```

#### Success Response (`200 OK`)

```json theme={null}
{
  "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`)

```json theme={null}
{
  "success": false,
  "status": 401,
  "message": "Invalid or inactive Client ID or API Key."
}
```

***

### 5. Create Credit Note

Create a new credit note.

```http theme={null}
POST /api/v1/external/billing/credit-notes
```

#### Request Body Example

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

#### Success Response (`201 Created`)

```json theme={null}
{
  "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`)

```json theme={null}
{
  "success": false,
  "status": 400,
  "message": "Credit note amount exceeds invoice balance"
}
```

***

### 6. List Debit Notes

Retrieve debit notes.

```http theme={null}
GET /api/v1/external/billing/debit-notes
```

#### Success Response (`200 OK`)

```json theme={null}
{
  "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.

```http theme={null}
POST /api/v1/external/billing/debit-notes
```

#### Request Body Example

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

#### Success Response (`201 Created`)

```json theme={null}
{
  "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`)

```json theme={null}
{
  "success": false,
  "status": 404,
  "message": "Referenced invoice not found"
}
```