User - Invoices

Base URL: https://your-domain.com

Admin endpoints for managing invoices. All endpoints require admin/staff authentication.

---

Fetch All Invoices

Retrieve a paginated list of all invoices with optional filters. Returns invoice data with package, reseller sales details, and salesperson information.

Property	Value
Endpoint	Fetch All Invoices
Method	GET
URL	/api/v1/invoices
Authentication	Bearer Token

Request Headers:

Header	Value	Required
Accept	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Query Parameters:

Required Parameters

Parameter	Type	Required	Description
isp_id	integer	Yes	ISP ID
branch_id	integer	Yes	Branch ID

Pagination Parameters

Parameter	Type	Required	Description
offset	integer	No	Pagination offset (default: 0)
limit	integer	No	Results per page (default: 100)

Filter Parameters

Parameter	Type	Required	Description
package_id	integer	No	Filter by package ID
salesperson_id	integer	No	Filter by salesperson ID
invoice_status	integer	No	Filter by status (1=Paid, 2=Unpaid, 3=Cancelled, 4=Refunded, 5=Partial, 6=Due)

Request Body: None

Success Response (200 OK):

{
    "success": true,
    "data": {
        "invoices": [
            {
                "id": 123,
                "invoice_number": "INV-2024-0123",
                "subscriber_id": 1,
                "subscriber_name": "John Doe",
                "amount": 1000,
                "status": "paid",
                "payment_date": "2024-01-15 10:30:00",
                "created_at": "2024-01-01 00:00:00"
            }
        ],
        "total": 150
    }
}

Error Response (401 Unauthorized):

{
    "success": false,
    "message": "Unauthenticated"
}

cURL Example:

curl -X GET "https://your-domain.com/api/v1/invoices?isp_id=1&branch_id=1&offset=0&limit=100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

---

View Invoice

View a single invoice with full details including package, subscriber, salesperson, action by data, and associated payment information.

Property	Value
Endpoint	View Invoice
Method	GET
URL	/api/v1/invoices/view
Authentication	Bearer Token

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	Invoice ID

Query Parameters:

Parameter	Type	Required	Description
isp_id	integer	Yes	ISP ID
branch_id	integer	Yes	Branch ID
user_id	integer	Yes	User ID

Success Response (200 OK):

{
    "success": true,
    "data": {
        "id": 123,
        "invoice_number": "INV-2024-0123",
        "subscriber_id": 1,
        "subscriber_name": "John Doe",
        "package_name": "10MB Package",
        "amount": 1000,
        "discount": 0,
        "tax": 0,
        "total": 1000,
        "status": "paid",
        "payment_method": "Cash",
        "payment_date": "2024-01-15 10:30:00",
        "notes": "",
        "created_at": "2024-01-01 00:00:00"
    }
}

Error Response (404 Not Found):

{
    "success": false,
    "message": "Invoice not found"
}

cURL Example:

curl -X GET "https://your-domain.com/api/v1/invoices/view?id=1&isp_id=1&branch_id=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

---

Update Invoice

Update invoice status or billing note. Cannot modify invoices that have been activated.

Property	Value
Endpoint	Update Invoice
Method	PUT
URL	/api/v1/invoices/update
Authentication	Bearer Token

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	Invoice ID

Request Headers:

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Request Body:

{
    "status": "paid",
    "notes": "Paid via cash"
}

Parameter	Type	Required	Description
status	string	No	Invoice status (paid, unpaid, pending)
notes	string	No	Additional notes

Success Response (200 OK):

{
    "success": true,
    "message": "Invoice updated successfully"
}

Error Response (404 Not Found):

{
    "success": false,
    "message": "Invoice not found"
}

cURL Example:

curl -X PUT "https://your-domain.com/api/v1/invoices/update" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "id": 1,
    "isp_id": 1,
    "branch_id": 1,
    "invoice_status": 1,
    "billing_note": "Payment received via cash"
  }'

---

Delete Invoice

Delete/Cancel an invoice. Cannot delete invoices that have been activated - mark as cancelled instead.

Property	Value
Endpoint	Delete Invoice
Method	DELETE
URL	/api/v1/invoices/delete
Authentication	Bearer Token

Query Parameters:

Parameter	Type	Required	Description
isp_id	integer	Yes	ISP ID
branch_id	integer	Yes	Branch ID
user_id	integer	Yes	User ID

Success Response (200 OK):

{
    "success": true,
    "message": "Invoice deleted successfully"
}

Error Response (404 Not Found):

{
    "success": false,
    "message": "Invoice not found"
}

Error Response (400 Bad Request):

{
    "success": false,
    "message": "Cannot delete paid invoice"
}

cURL Example:

curl -X DELETE "https://your-domain.com/api/v1/invoices/delete?id=1&isp_id=1&branch_id=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"