> For the complete documentation index, see [llms.txt](https://docs.skhokho.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skhokho.ai/finance/bills.md).

# 💳 Bills

Accounts payable and bill management

## List bills

> List all bills for an organization

```json
{"openapi":"3.0.3","info":{"title":"Skhokho API","version":"v1.0"},"tags":[{"name":"Bills","description":"Accounts payable and bill management"}],"servers":[{"url":"https://skhokho.ai","description":"Production"},{"url":"http://102.209.118.152:8000/","description":"Local"},{"url":"https://dev.skhokho.ai","description":"Development"}],"security":[{"basicAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"schemas":{"BillList":{"type":"object","description":"Lightweight version for list views.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string"},"bill_number":{"type":"string","maxLength":100},"supplier_invoice_number":{"type":"string","nullable":true,"maxLength":100},"status":{"enum":["received","approved","paid","partially_paid","overdue","disputed","cancelled"],"type":"string","description":"* `received` - Received\n* `approved` - Approved for Payment\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `disputed` - Disputed\n* `cancelled` - Cancelled"},"status_display":{"type":"string","readOnly":true},"vendor":{"allOf":[{"$ref":"#/components/schemas/FinanceExpenseVendorMini"}],"readOnly":true},"bill_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"paid_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"remaining_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true},"is_overdue":{"type":"boolean","readOnly":true},"date_created":{"type":"string","format":"date-time","readOnly":true,"nullable":true}},"required":["bill_date","bill_number","date_created","due_date","is_overdue","remaining_amount","status_display","title","total_amount","vendor"]},"FinanceExpenseVendorMini":{"type":"object","description":"Lightweight serializer for Vendor references.","properties":{"unique_id":{"type":"string"},"name":{"type":"string","readOnly":true}},"required":["name","unique_id"]}}},"paths":{"/api/v1.0/organisation/{org_id}/bills/":{"get":{"operationId":"organisation_bills_list","description":"List all bills for an organization","summary":"List bills","parameters":[{"in":"query","name":"from_date","schema":{"type":"string","format":"date"},"description":"Filter bills from this bill_date (YYYY-MM-DD)"},{"in":"path","name":"org_id","schema":{"type":"string"},"required":true},{"in":"query","name":"overdue","schema":{"type":"boolean"},"description":"Filter overdue bills (true/false)"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search bill_number, supplier_invoice_number, or bill title"},{"in":"query","name":"status","schema":{"type":"string","enum":["approved","cancelled","disputed","draft","paid","partially_paid","received"]},"description":"Filter by bill status"},{"in":"query","name":"to_date","schema":{"type":"string","format":"date"},"description":"Filter bills up to this bill_date (YYYY-MM-DD)"},{"in":"query","name":"vendor_id","schema":{"type":"string"},"description":"Filter by vendor unique_id"}],"tags":["Bills"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BillList"}}}},"description":""},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}}}}
```

## Create bill

> Create a new bill

```json
{"openapi":"3.0.3","info":{"title":"Skhokho API","version":"v1.0"},"tags":[{"name":"Bills","description":"Accounts payable and bill management"}],"servers":[{"url":"https://skhokho.ai","description":"Production"},{"url":"http://102.209.118.152:8000/","description":"Local"},{"url":"https://dev.skhokho.ai","description":"Development"}],"security":[{"basicAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"schemas":{"BillRequest":{"type":"object","description":"Comprehensive serializer for Bill model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"bill_number":{"type":"string","minLength":1,"maxLength":100},"supplier_invoice_number":{"type":"string","nullable":true,"maxLength":100},"status":{"enum":["received","approved","paid","partially_paid","overdue","disputed","cancelled"],"type":"string","description":"* `received` - Received\n* `approved` - Approved for Payment\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `disputed` - Disputed\n* `cancelled` - Cancelled"},"vendor_id":{"type":"string","writeOnly":true,"nullable":true,"minLength":1},"bill_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"received_date":{"type":"string","format":"date"},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"tax_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Tax Rate (%)"},"tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"paid_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"document":{"type":"string","format":"binary","nullable":true,"title":"Bill Document","description":"Scanned bill document (PDF, image)"}},"required":["bill_date","bill_number","due_date","subtotal","title","total_amount"]},"Bill":{"type":"object","description":"Comprehensive serializer for Bill model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string"},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"bill_number":{"type":"string","maxLength":100},"supplier_invoice_number":{"type":"string","nullable":true,"maxLength":100},"status":{"enum":["received","approved","paid","partially_paid","overdue","disputed","cancelled"],"type":"string","description":"* `received` - Received\n* `approved` - Approved for Payment\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `disputed` - Disputed\n* `cancelled` - Cancelled"},"status_display":{"type":"string","readOnly":true},"vendor":{"allOf":[{"$ref":"#/components/schemas/FinanceExpenseVendorMini"}],"readOnly":true},"bill_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"received_date":{"type":"string","format":"date"},"paid_date":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"tax_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Tax Rate (%)"},"tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"paid_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"remaining_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true},"payment_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","readOnly":true},"is_overdue":{"type":"boolean","readOnly":true},"document":{"type":"string","format":"uri","nullable":true,"title":"Bill Document","description":"Scanned bill document (PDF, image)"},"document_url":{"type":"string","nullable":true,"readOnly":true},"created_by":{"allOf":[{"$ref":"#/components/schemas/FinancePersonMini"}],"readOnly":true},"date_created":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"last_updated":{"type":"string","format":"date-time","readOnly":true,"nullable":true}},"required":["bill_date","bill_number","created_by","date_created","document_url","due_date","is_overdue","last_updated","paid_date","payment_percentage","remaining_amount","status_display","subtotal","title","total_amount","vendor"]},"FinanceExpenseVendorMini":{"type":"object","description":"Lightweight serializer for Vendor references.","properties":{"unique_id":{"type":"string"},"name":{"type":"string","readOnly":true}},"required":["name","unique_id"]},"FinancePersonMini":{"type":"object","description":"Lightweight serializer for Person model.\nUsed for nested person references in financial documents.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"full_name":{"type":"string","readOnly":true}},"required":["full_name"]}}},"paths":{"/api/v1.0/organisation/{org_id}/bills/create/":{"post":{"operationId":"organisation_bills_create_create","description":"Create a new bill","summary":"Create bill","parameters":[{"in":"path","name":"org_id","schema":{"type":"string"},"required":true}],"tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/BillRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/BillRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}},"description":""},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}}}}
```

## Retrieve bill

> Retrieve a specific bill with full details

```json
{"openapi":"3.0.3","info":{"title":"Skhokho API","version":"v1.0"},"tags":[{"name":"Bills","description":"Accounts payable and bill management"}],"servers":[{"url":"https://skhokho.ai","description":"Production"},{"url":"http://102.209.118.152:8000/","description":"Local"},{"url":"https://dev.skhokho.ai","description":"Development"}],"security":[{"basicAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"schemas":{"Bill":{"type":"object","description":"Comprehensive serializer for Bill model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string"},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"bill_number":{"type":"string","maxLength":100},"supplier_invoice_number":{"type":"string","nullable":true,"maxLength":100},"status":{"enum":["received","approved","paid","partially_paid","overdue","disputed","cancelled"],"type":"string","description":"* `received` - Received\n* `approved` - Approved for Payment\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `disputed` - Disputed\n* `cancelled` - Cancelled"},"status_display":{"type":"string","readOnly":true},"vendor":{"allOf":[{"$ref":"#/components/schemas/FinanceExpenseVendorMini"}],"readOnly":true},"bill_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"received_date":{"type":"string","format":"date"},"paid_date":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"tax_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Tax Rate (%)"},"tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"paid_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"remaining_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true},"payment_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","readOnly":true},"is_overdue":{"type":"boolean","readOnly":true},"document":{"type":"string","format":"uri","nullable":true,"title":"Bill Document","description":"Scanned bill document (PDF, image)"},"document_url":{"type":"string","nullable":true,"readOnly":true},"created_by":{"allOf":[{"$ref":"#/components/schemas/FinancePersonMini"}],"readOnly":true},"date_created":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"last_updated":{"type":"string","format":"date-time","readOnly":true,"nullable":true}},"required":["bill_date","bill_number","created_by","date_created","document_url","due_date","is_overdue","last_updated","paid_date","payment_percentage","remaining_amount","status_display","subtotal","title","total_amount","vendor"]},"FinanceExpenseVendorMini":{"type":"object","description":"Lightweight serializer for Vendor references.","properties":{"unique_id":{"type":"string"},"name":{"type":"string","readOnly":true}},"required":["name","unique_id"]},"FinancePersonMini":{"type":"object","description":"Lightweight serializer for Person model.\nUsed for nested person references in financial documents.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"full_name":{"type":"string","readOnly":true}},"required":["full_name"]}}},"paths":{"/api/v1.0/organisation/{org_id}/bills/{bill_id}/":{"get":{"operationId":"organisation_bills_retrieve","description":"Retrieve a specific bill with full details","summary":"Retrieve bill","parameters":[{"in":"path","name":"bill_id","schema":{"type":"string"},"required":true},{"in":"path","name":"org_id","schema":{"type":"string"},"required":true}],"tags":["Bills"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}},"description":""},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}}}}
```

## Update bill

> Update an existing bill

```json
{"openapi":"3.0.3","info":{"title":"Skhokho API","version":"v1.0"},"tags":[{"name":"Bills","description":"Accounts payable and bill management"}],"servers":[{"url":"https://skhokho.ai","description":"Production"},{"url":"http://102.209.118.152:8000/","description":"Local"},{"url":"https://dev.skhokho.ai","description":"Development"}],"security":[{"basicAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"schemas":{"BillRequest":{"type":"object","description":"Comprehensive serializer for Bill model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"bill_number":{"type":"string","minLength":1,"maxLength":100},"supplier_invoice_number":{"type":"string","nullable":true,"maxLength":100},"status":{"enum":["received","approved","paid","partially_paid","overdue","disputed","cancelled"],"type":"string","description":"* `received` - Received\n* `approved` - Approved for Payment\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `disputed` - Disputed\n* `cancelled` - Cancelled"},"vendor_id":{"type":"string","writeOnly":true,"nullable":true,"minLength":1},"bill_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"received_date":{"type":"string","format":"date"},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"tax_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Tax Rate (%)"},"tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"paid_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"document":{"type":"string","format":"binary","nullable":true,"title":"Bill Document","description":"Scanned bill document (PDF, image)"}},"required":["bill_date","bill_number","due_date","subtotal","title","total_amount"]},"Bill":{"type":"object","description":"Comprehensive serializer for Bill model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string"},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"bill_number":{"type":"string","maxLength":100},"supplier_invoice_number":{"type":"string","nullable":true,"maxLength":100},"status":{"enum":["received","approved","paid","partially_paid","overdue","disputed","cancelled"],"type":"string","description":"* `received` - Received\n* `approved` - Approved for Payment\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `disputed` - Disputed\n* `cancelled` - Cancelled"},"status_display":{"type":"string","readOnly":true},"vendor":{"allOf":[{"$ref":"#/components/schemas/FinanceExpenseVendorMini"}],"readOnly":true},"bill_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"received_date":{"type":"string","format":"date"},"paid_date":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"tax_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Tax Rate (%)"},"tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"paid_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"remaining_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true},"payment_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","readOnly":true},"is_overdue":{"type":"boolean","readOnly":true},"document":{"type":"string","format":"uri","nullable":true,"title":"Bill Document","description":"Scanned bill document (PDF, image)"},"document_url":{"type":"string","nullable":true,"readOnly":true},"created_by":{"allOf":[{"$ref":"#/components/schemas/FinancePersonMini"}],"readOnly":true},"date_created":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"last_updated":{"type":"string","format":"date-time","readOnly":true,"nullable":true}},"required":["bill_date","bill_number","created_by","date_created","document_url","due_date","is_overdue","last_updated","paid_date","payment_percentage","remaining_amount","status_display","subtotal","title","total_amount","vendor"]},"FinanceExpenseVendorMini":{"type":"object","description":"Lightweight serializer for Vendor references.","properties":{"unique_id":{"type":"string"},"name":{"type":"string","readOnly":true}},"required":["name","unique_id"]},"FinancePersonMini":{"type":"object","description":"Lightweight serializer for Person model.\nUsed for nested person references in financial documents.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"full_name":{"type":"string","readOnly":true}},"required":["full_name"]}}},"paths":{"/api/v1.0/organisation/{org_id}/bills/{bill_id}/update/":{"put":{"operationId":"organisation_bills_update_update","description":"Update an existing bill","summary":"Update bill","parameters":[{"in":"path","name":"bill_id","schema":{"type":"string"},"required":true},{"in":"path","name":"org_id","schema":{"type":"string"},"required":true}],"tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/BillRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/BillRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}},"description":""},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}}}}
```

## Update bill

> Update an existing bill

```json
{"openapi":"3.0.3","info":{"title":"Skhokho API","version":"v1.0"},"tags":[{"name":"Bills","description":"Accounts payable and bill management"}],"servers":[{"url":"https://skhokho.ai","description":"Production"},{"url":"http://102.209.118.152:8000/","description":"Local"},{"url":"https://dev.skhokho.ai","description":"Development"}],"security":[{"basicAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"schemas":{"PatchedBillRequest":{"type":"object","description":"Comprehensive serializer for Bill model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"bill_number":{"type":"string","minLength":1,"maxLength":100},"supplier_invoice_number":{"type":"string","nullable":true,"maxLength":100},"status":{"enum":["received","approved","paid","partially_paid","overdue","disputed","cancelled"],"type":"string","description":"* `received` - Received\n* `approved` - Approved for Payment\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `disputed` - Disputed\n* `cancelled` - Cancelled"},"vendor_id":{"type":"string","writeOnly":true,"nullable":true,"minLength":1},"bill_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"received_date":{"type":"string","format":"date"},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"tax_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Tax Rate (%)"},"tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"paid_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"document":{"type":"string","format":"binary","nullable":true,"title":"Bill Document","description":"Scanned bill document (PDF, image)"}}},"Bill":{"type":"object","description":"Comprehensive serializer for Bill model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string"},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"bill_number":{"type":"string","maxLength":100},"supplier_invoice_number":{"type":"string","nullable":true,"maxLength":100},"status":{"enum":["received","approved","paid","partially_paid","overdue","disputed","cancelled"],"type":"string","description":"* `received` - Received\n* `approved` - Approved for Payment\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `disputed` - Disputed\n* `cancelled` - Cancelled"},"status_display":{"type":"string","readOnly":true},"vendor":{"allOf":[{"$ref":"#/components/schemas/FinanceExpenseVendorMini"}],"readOnly":true},"bill_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"received_date":{"type":"string","format":"date"},"paid_date":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"tax_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Tax Rate (%)"},"tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"paid_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"remaining_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true},"payment_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","readOnly":true},"is_overdue":{"type":"boolean","readOnly":true},"document":{"type":"string","format":"uri","nullable":true,"title":"Bill Document","description":"Scanned bill document (PDF, image)"},"document_url":{"type":"string","nullable":true,"readOnly":true},"created_by":{"allOf":[{"$ref":"#/components/schemas/FinancePersonMini"}],"readOnly":true},"date_created":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"last_updated":{"type":"string","format":"date-time","readOnly":true,"nullable":true}},"required":["bill_date","bill_number","created_by","date_created","document_url","due_date","is_overdue","last_updated","paid_date","payment_percentage","remaining_amount","status_display","subtotal","title","total_amount","vendor"]},"FinanceExpenseVendorMini":{"type":"object","description":"Lightweight serializer for Vendor references.","properties":{"unique_id":{"type":"string"},"name":{"type":"string","readOnly":true}},"required":["name","unique_id"]},"FinancePersonMini":{"type":"object","description":"Lightweight serializer for Person model.\nUsed for nested person references in financial documents.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"full_name":{"type":"string","readOnly":true}},"required":["full_name"]}}},"paths":{"/api/v1.0/organisation/{org_id}/bills/{bill_id}/update/":{"patch":{"operationId":"organisation_bills_update_partial_update","description":"Update an existing bill","summary":"Update bill","parameters":[{"in":"path","name":"bill_id","schema":{"type":"string"},"required":true},{"in":"path","name":"org_id","schema":{"type":"string"},"required":true}],"tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchedBillRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PatchedBillRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PatchedBillRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}},"description":""},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}}}}
```

## Perform bill action

> Perform an action on a bill using query parameter.\
>     \
>     \*\*Available Actions:\*\*\
>     \- \`mark\_received\` - Mark a pending bill as received\
>     \- \`approve\` - Approve a received bill for payment\
>     \- \`mark\_paid\` - Mark an approved bill as fully paid\
>     \- \`mark\_partially\_paid\` - Mark a bill as partially paid\
>     \- \`mark\_disputed\` - Mark a bill as disputed\
>     \- \`mark\_cancelled\` - Mark a bill as cancelled\
>     \- \`record\_payment\` - Record a payment made for the bill (requires \`amount\` parameter)\
>     \
>     \*\*Examples:\*\*\
>     \- \`/bills/{id}/action?action=mark\_received\`\
>     \- \`/bills/{id}/action?action=approve\`\
>     \- \`/bills/{id}/action?action=mark\_paid\`\
>     \- \`/bills/{id}/action?action=record\_payment\&amount=500.00\`\
>     

```json
{"openapi":"3.0.3","info":{"title":"Skhokho API","version":"v1.0"},"tags":[{"name":"Bills","description":"Accounts payable and bill management"}],"servers":[{"url":"https://skhokho.ai","description":"Production"},{"url":"http://102.209.118.152:8000/","description":"Local"},{"url":"https://dev.skhokho.ai","description":"Development"}],"security":[{"basicAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"schemas":{"Bill":{"type":"object","description":"Comprehensive serializer for Bill model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string"},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"bill_number":{"type":"string","maxLength":100},"supplier_invoice_number":{"type":"string","nullable":true,"maxLength":100},"status":{"enum":["received","approved","paid","partially_paid","overdue","disputed","cancelled"],"type":"string","description":"* `received` - Received\n* `approved` - Approved for Payment\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `disputed` - Disputed\n* `cancelled` - Cancelled"},"status_display":{"type":"string","readOnly":true},"vendor":{"allOf":[{"$ref":"#/components/schemas/FinanceExpenseVendorMini"}],"readOnly":true},"bill_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"received_date":{"type":"string","format":"date"},"paid_date":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"tax_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Tax Rate (%)"},"tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"paid_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"remaining_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true},"payment_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","readOnly":true},"is_overdue":{"type":"boolean","readOnly":true},"document":{"type":"string","format":"uri","nullable":true,"title":"Bill Document","description":"Scanned bill document (PDF, image)"},"document_url":{"type":"string","nullable":true,"readOnly":true},"created_by":{"allOf":[{"$ref":"#/components/schemas/FinancePersonMini"}],"readOnly":true},"date_created":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"last_updated":{"type":"string","format":"date-time","readOnly":true,"nullable":true}},"required":["bill_date","bill_number","created_by","date_created","document_url","due_date","is_overdue","last_updated","paid_date","payment_percentage","remaining_amount","status_display","subtotal","title","total_amount","vendor"]},"FinanceExpenseVendorMini":{"type":"object","description":"Lightweight serializer for Vendor references.","properties":{"unique_id":{"type":"string"},"name":{"type":"string","readOnly":true}},"required":["name","unique_id"]},"FinancePersonMini":{"type":"object","description":"Lightweight serializer for Person model.\nUsed for nested person references in financial documents.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"full_name":{"type":"string","readOnly":true}},"required":["full_name"]}}},"paths":{"/api/v1.0/organisation/{org_id}/bills/{bill_id}/action/":{"get":{"operationId":"organisation_bills_action_retrieve","description":"Perform an action on a bill using query parameter.\n    \n    **Available Actions:**\n    - `mark_received` - Mark a pending bill as received\n    - `approve` - Approve a received bill for payment\n    - `mark_paid` - Mark an approved bill as fully paid\n    - `mark_partially_paid` - Mark a bill as partially paid\n    - `mark_disputed` - Mark a bill as disputed\n    - `mark_cancelled` - Mark a bill as cancelled\n    - `record_payment` - Record a payment made for the bill (requires `amount` parameter)\n    \n    **Examples:**\n    - `/bills/{id}/action?action=mark_received`\n    - `/bills/{id}/action?action=approve`\n    - `/bills/{id}/action?action=mark_paid`\n    - `/bills/{id}/action?action=record_payment&amount=500.00`\n    ","summary":"Perform bill action","parameters":[{"in":"query","name":"action","schema":{"type":"string","enum":["approve","mark_cancelled","mark_disputed","mark_paid","mark_partially_paid","mark_received","record_payment"]},"description":"The action to perform on the bill","required":true},{"in":"query","name":"amount","schema":{"type":"number","format":"double"},"description":"Payment amount (required when action=record_payment)"},{"in":"path","name":"bill_id","schema":{"type":"string"},"required":true},{"in":"path","name":"org_id","schema":{"type":"string"},"required":true},{"in":"query","name":"payment_date","schema":{"type":"string"},"description":"Payment date in YYYY-MM-DD format (optional, defaults to today)"}],"tags":["Bills"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}},"description":""},"400":{"description":"Bad Request - Invalid action or invalid state transition"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}}}}
```