# 💳 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"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.skhokho.ai/finance/bills.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.