> 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/invoices.md).

# 🧾 Invoices

Invoice creation, management, and tracking

## List invoices

> List all invoices for an organization

```json
{"openapi":"3.0.3","info":{"title":"Skhokho API","version":"v1.0"},"tags":[{"name":"Invoices","description":"Invoice creation, management, and tracking"}],"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":{"InvoiceList":{"type":"object","description":"Lightweight version for list views.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string"},"invoice_number":{"type":"string","maxLength":100},"status":{"enum":["draft","sent","viewed","paid","partially_paid","overdue","cancelled","refunded"],"type":"string","description":"* `draft` - Draft\n* `sent` - Sent\n* `viewed` - Viewed by Client\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `cancelled` - Cancelled\n* `refunded` - Refunded"},"status_display":{"type":"string","readOnly":true},"invoice_date":{"type":"string","format":"date","nullable":true},"due_date":{"type":"string","format":"date"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Subtotal + Total Tax Amount"},"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},"currency":{"type":"string","readOnly":true},"client":{"allOf":[{"$ref":"#/components/schemas/FinanceClientMini"}],"readOnly":true},"date_created":{"type":"string","format":"date-time","readOnly":true,"nullable":true}},"required":["client","currency","date_created","due_date","invoice_number","is_overdue","remaining_amount","status_display","title","total_amount"]},"FinanceClientMini":{"type":"object","description":"Lightweight serializer for Client model.\nUsed for nested client references in invoices and quotes.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"name":{"type":"string","readOnly":true},"entity_type":{"enum":["individual","company","non_profit","government","partnership","other"],"type":"string","description":"* `individual` - Individual\n* `company` - Company\n* `non_profit` - Non-Profit Organization\n* `government` - Government Entity\n* `partnership` - Partnership\n* `other` - Other"}},"required":["name"]}}},"paths":{"/api/v1.0/organisation/{org_id}/invoices/":{"get":{"operationId":"organisation_invoices_list","description":"List all invoices for an organization","summary":"List invoices","parameters":[{"in":"query","name":"client_id","schema":{"type":"string"},"description":"Filter by client unique_id"},{"in":"query","name":"from_date","schema":{"type":"string"},"description":"Filter invoices from this invoice_date (YYYY-MM-DD)"},{"in":"path","name":"org_id","schema":{"type":"string"},"required":true},{"in":"query","name":"overdue","schema":{"type":"string"},"description":"Filter overdue invoices (true/false)"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search invoice_number or title"},{"in":"query","name":"status","schema":{"type":"string","enum":["cancelled","draft","paid","partially_paid","sent","viewed"]},"description":"Filter by invoice status"},{"in":"query","name":"to_date","schema":{"type":"string"},"description":"Filter invoices up to this invoice_date (YYYY-MM-DD)"}],"tags":["Invoices"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceList"}}}},"description":""},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}}}}
```

## Create invoice

> Create a new invoice

```json
{"openapi":"3.0.3","info":{"title":"Skhokho API","version":"v1.0"},"tags":[{"name":"Invoices","description":"Invoice creation, management, and tracking"}],"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":{"InvoiceRequest":{"type":"object","description":"Comprehensive serializer for Invoice model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"invoice_number":{"type":"string","minLength":1,"maxLength":100},"status":{"enum":["draft","sent","viewed","paid","partially_paid","overdue","cancelled","refunded"],"type":"string","description":"* `draft` - Draft\n* `sent` - Sent\n* `viewed` - Viewed by Client\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `cancelled` - Cancelled\n* `refunded` - Refunded"},"invoice_date":{"type":"string","format":"date","nullable":true},"due_date":{"type":"string","format":"date"},"paid_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"client_id":{"type":"string","writeOnly":true,"minLength":1,"description":"Client unique_id (required)"},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItemRequest"}}},"required":["client_id","due_date","invoice_number","title"]},"InvoiceItemRequest":{"type":"object","description":"Serializer for invoice line items.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"product_id":{"type":"string","writeOnly":true,"nullable":true,"minLength":1},"service_id":{"type":"string","writeOnly":true,"nullable":true,"minLength":1},"quantity":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"unit_price":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"discount_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Discount %"},"vat_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"VAT Rate (%)","description":"VAT/tax rate percentage for this line item"},"currency":{"type":"string","minLength":1,"description":"Currency code (ISO 4217) for this line item","maxLength":3}},"required":["quantity","unit_price"]},"Invoice":{"type":"object","description":"Comprehensive serializer for Invoice model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string"},"description":{"type":"string","nullable":true},"invoice_number":{"type":"string","maxLength":100},"status":{"enum":["draft","sent","viewed","paid","partially_paid","overdue","cancelled","refunded"],"type":"string","description":"* `draft` - Draft\n* `sent` - Sent\n* `viewed` - Viewed by Client\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `cancelled` - Cancelled\n* `refunded` - Refunded"},"status_display":{"type":"string","readOnly":true},"invoice_date":{"type":"string","format":"date","nullable":true},"due_date":{"type":"string","format":"date"},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Calculated from line items"},"total_tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Total VAT/tax from all line items"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Subtotal + Total Tax Amount"},"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},"currency":{"type":"string","readOnly":true},"client":{"allOf":[{"$ref":"#/components/schemas/FinanceClientMini"}],"readOnly":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"}},"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":["client","created_by","currency","date_created","due_date","invoice_number","is_overdue","last_updated","remaining_amount","status_display","subtotal","title","total_amount","total_tax_amount"]},"FinanceClientMini":{"type":"object","description":"Lightweight serializer for Client model.\nUsed for nested client references in invoices and quotes.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"name":{"type":"string","readOnly":true},"entity_type":{"enum":["individual","company","non_profit","government","partnership","other"],"type":"string","description":"* `individual` - Individual\n* `company` - Company\n* `non_profit` - Non-Profit Organization\n* `government` - Government Entity\n* `partnership` - Partnership\n* `other` - Other"}},"required":["name"]},"InvoiceItem":{"type":"object","description":"Serializer for invoice line items.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"item_name":{"type":"string","readOnly":true},"quantity":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"unit_price":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"discount_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Discount %"},"vat_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"VAT Rate (%)","description":"VAT/tax rate percentage for this line item"},"currency":{"type":"string","description":"Currency code (ISO 4217) for this line item","maxLength":3},"line_subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true},"line_vat_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true},"line_total":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true}},"required":["item_name","line_subtotal","line_total","line_vat_amount","quantity","unit_price"]},"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}/invoices/create/":{"post":{"operationId":"organisation_invoices_create_create","description":"Create a new invoice","summary":"Create invoice","parameters":[{"in":"path","name":"org_id","schema":{"type":"string"},"required":true}],"tags":["Invoices"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/InvoiceRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/InvoiceRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}},"description":""},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}}}}
```

## Retrieve invoice

> Retrieve a specific invoice with full details

```json
{"openapi":"3.0.3","info":{"title":"Skhokho API","version":"v1.0"},"tags":[{"name":"Invoices","description":"Invoice creation, management, and tracking"}],"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":{"Invoice":{"type":"object","description":"Comprehensive serializer for Invoice model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string"},"description":{"type":"string","nullable":true},"invoice_number":{"type":"string","maxLength":100},"status":{"enum":["draft","sent","viewed","paid","partially_paid","overdue","cancelled","refunded"],"type":"string","description":"* `draft` - Draft\n* `sent` - Sent\n* `viewed` - Viewed by Client\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `cancelled` - Cancelled\n* `refunded` - Refunded"},"status_display":{"type":"string","readOnly":true},"invoice_date":{"type":"string","format":"date","nullable":true},"due_date":{"type":"string","format":"date"},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Calculated from line items"},"total_tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Total VAT/tax from all line items"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Subtotal + Total Tax Amount"},"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},"currency":{"type":"string","readOnly":true},"client":{"allOf":[{"$ref":"#/components/schemas/FinanceClientMini"}],"readOnly":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"}},"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":["client","created_by","currency","date_created","due_date","invoice_number","is_overdue","last_updated","remaining_amount","status_display","subtotal","title","total_amount","total_tax_amount"]},"FinanceClientMini":{"type":"object","description":"Lightweight serializer for Client model.\nUsed for nested client references in invoices and quotes.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"name":{"type":"string","readOnly":true},"entity_type":{"enum":["individual","company","non_profit","government","partnership","other"],"type":"string","description":"* `individual` - Individual\n* `company` - Company\n* `non_profit` - Non-Profit Organization\n* `government` - Government Entity\n* `partnership` - Partnership\n* `other` - Other"}},"required":["name"]},"InvoiceItem":{"type":"object","description":"Serializer for invoice line items.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"item_name":{"type":"string","readOnly":true},"quantity":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"unit_price":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"discount_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Discount %"},"vat_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"VAT Rate (%)","description":"VAT/tax rate percentage for this line item"},"currency":{"type":"string","description":"Currency code (ISO 4217) for this line item","maxLength":3},"line_subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true},"line_vat_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true},"line_total":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true}},"required":["item_name","line_subtotal","line_total","line_vat_amount","quantity","unit_price"]},"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}/invoices/{invoice_id}/":{"get":{"operationId":"organisation_invoices_retrieve","description":"Retrieve a specific invoice with full details","summary":"Retrieve invoice","parameters":[{"in":"path","name":"invoice_id","schema":{"type":"string"},"required":true},{"in":"path","name":"org_id","schema":{"type":"string"},"required":true}],"tags":["Invoices"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}},"description":""},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}}}}
```

## Update invoice

> Update an existing invoice

```json
{"openapi":"3.0.3","info":{"title":"Skhokho API","version":"v1.0"},"tags":[{"name":"Invoices","description":"Invoice creation, management, and tracking"}],"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":{"InvoiceRequest":{"type":"object","description":"Comprehensive serializer for Invoice model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"invoice_number":{"type":"string","minLength":1,"maxLength":100},"status":{"enum":["draft","sent","viewed","paid","partially_paid","overdue","cancelled","refunded"],"type":"string","description":"* `draft` - Draft\n* `sent` - Sent\n* `viewed` - Viewed by Client\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `cancelled` - Cancelled\n* `refunded` - Refunded"},"invoice_date":{"type":"string","format":"date","nullable":true},"due_date":{"type":"string","format":"date"},"paid_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"client_id":{"type":"string","writeOnly":true,"minLength":1,"description":"Client unique_id (required)"},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItemRequest"}}},"required":["client_id","due_date","invoice_number","title"]},"InvoiceItemRequest":{"type":"object","description":"Serializer for invoice line items.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"product_id":{"type":"string","writeOnly":true,"nullable":true,"minLength":1},"service_id":{"type":"string","writeOnly":true,"nullable":true,"minLength":1},"quantity":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"unit_price":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"discount_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Discount %"},"vat_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"VAT Rate (%)","description":"VAT/tax rate percentage for this line item"},"currency":{"type":"string","minLength":1,"description":"Currency code (ISO 4217) for this line item","maxLength":3}},"required":["quantity","unit_price"]},"Invoice":{"type":"object","description":"Comprehensive serializer for Invoice model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string"},"description":{"type":"string","nullable":true},"invoice_number":{"type":"string","maxLength":100},"status":{"enum":["draft","sent","viewed","paid","partially_paid","overdue","cancelled","refunded"],"type":"string","description":"* `draft` - Draft\n* `sent` - Sent\n* `viewed` - Viewed by Client\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `cancelled` - Cancelled\n* `refunded` - Refunded"},"status_display":{"type":"string","readOnly":true},"invoice_date":{"type":"string","format":"date","nullable":true},"due_date":{"type":"string","format":"date"},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Calculated from line items"},"total_tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Total VAT/tax from all line items"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Subtotal + Total Tax Amount"},"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},"currency":{"type":"string","readOnly":true},"client":{"allOf":[{"$ref":"#/components/schemas/FinanceClientMini"}],"readOnly":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"}},"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":["client","created_by","currency","date_created","due_date","invoice_number","is_overdue","last_updated","remaining_amount","status_display","subtotal","title","total_amount","total_tax_amount"]},"FinanceClientMini":{"type":"object","description":"Lightweight serializer for Client model.\nUsed for nested client references in invoices and quotes.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"name":{"type":"string","readOnly":true},"entity_type":{"enum":["individual","company","non_profit","government","partnership","other"],"type":"string","description":"* `individual` - Individual\n* `company` - Company\n* `non_profit` - Non-Profit Organization\n* `government` - Government Entity\n* `partnership` - Partnership\n* `other` - Other"}},"required":["name"]},"InvoiceItem":{"type":"object","description":"Serializer for invoice line items.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"item_name":{"type":"string","readOnly":true},"quantity":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"unit_price":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"discount_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Discount %"},"vat_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"VAT Rate (%)","description":"VAT/tax rate percentage for this line item"},"currency":{"type":"string","description":"Currency code (ISO 4217) for this line item","maxLength":3},"line_subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true},"line_vat_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true},"line_total":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true}},"required":["item_name","line_subtotal","line_total","line_vat_amount","quantity","unit_price"]},"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}/invoices/{invoice_id}/update/":{"put":{"operationId":"organisation_invoices_update_update","description":"Update an existing invoice","summary":"Update invoice","parameters":[{"in":"path","name":"invoice_id","schema":{"type":"string"},"required":true},{"in":"path","name":"org_id","schema":{"type":"string"},"required":true}],"tags":["Invoices"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/InvoiceRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/InvoiceRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}},"description":""},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}}}}
```

## Update invoice

> Update an existing invoice

```json
{"openapi":"3.0.3","info":{"title":"Skhokho API","version":"v1.0"},"tags":[{"name":"Invoices","description":"Invoice creation, management, and tracking"}],"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":{"PatchedInvoiceRequest":{"type":"object","description":"Comprehensive serializer for Invoice model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"invoice_number":{"type":"string","minLength":1,"maxLength":100},"status":{"enum":["draft","sent","viewed","paid","partially_paid","overdue","cancelled","refunded"],"type":"string","description":"* `draft` - Draft\n* `sent` - Sent\n* `viewed` - Viewed by Client\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `cancelled` - Cancelled\n* `refunded` - Refunded"},"invoice_date":{"type":"string","format":"date","nullable":true},"due_date":{"type":"string","format":"date"},"paid_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"client_id":{"type":"string","writeOnly":true,"minLength":1,"description":"Client unique_id (required)"},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItemRequest"}}}},"InvoiceItemRequest":{"type":"object","description":"Serializer for invoice line items.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"product_id":{"type":"string","writeOnly":true,"nullable":true,"minLength":1},"service_id":{"type":"string","writeOnly":true,"nullable":true,"minLength":1},"quantity":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"unit_price":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"discount_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Discount %"},"vat_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"VAT Rate (%)","description":"VAT/tax rate percentage for this line item"},"currency":{"type":"string","minLength":1,"description":"Currency code (ISO 4217) for this line item","maxLength":3}},"required":["quantity","unit_price"]},"Invoice":{"type":"object","description":"Comprehensive serializer for Invoice model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string"},"description":{"type":"string","nullable":true},"invoice_number":{"type":"string","maxLength":100},"status":{"enum":["draft","sent","viewed","paid","partially_paid","overdue","cancelled","refunded"],"type":"string","description":"* `draft` - Draft\n* `sent` - Sent\n* `viewed` - Viewed by Client\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `cancelled` - Cancelled\n* `refunded` - Refunded"},"status_display":{"type":"string","readOnly":true},"invoice_date":{"type":"string","format":"date","nullable":true},"due_date":{"type":"string","format":"date"},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Calculated from line items"},"total_tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Total VAT/tax from all line items"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Subtotal + Total Tax Amount"},"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},"currency":{"type":"string","readOnly":true},"client":{"allOf":[{"$ref":"#/components/schemas/FinanceClientMini"}],"readOnly":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"}},"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":["client","created_by","currency","date_created","due_date","invoice_number","is_overdue","last_updated","remaining_amount","status_display","subtotal","title","total_amount","total_tax_amount"]},"FinanceClientMini":{"type":"object","description":"Lightweight serializer for Client model.\nUsed for nested client references in invoices and quotes.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"name":{"type":"string","readOnly":true},"entity_type":{"enum":["individual","company","non_profit","government","partnership","other"],"type":"string","description":"* `individual` - Individual\n* `company` - Company\n* `non_profit` - Non-Profit Organization\n* `government` - Government Entity\n* `partnership` - Partnership\n* `other` - Other"}},"required":["name"]},"InvoiceItem":{"type":"object","description":"Serializer for invoice line items.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"item_name":{"type":"string","readOnly":true},"quantity":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"unit_price":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"discount_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Discount %"},"vat_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"VAT Rate (%)","description":"VAT/tax rate percentage for this line item"},"currency":{"type":"string","description":"Currency code (ISO 4217) for this line item","maxLength":3},"line_subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true},"line_vat_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true},"line_total":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true}},"required":["item_name","line_subtotal","line_total","line_vat_amount","quantity","unit_price"]},"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}/invoices/{invoice_id}/update/":{"patch":{"operationId":"organisation_invoices_update_partial_update","description":"Update an existing invoice","summary":"Update invoice","parameters":[{"in":"path","name":"invoice_id","schema":{"type":"string"},"required":true},{"in":"path","name":"org_id","schema":{"type":"string"},"required":true}],"tags":["Invoices"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchedInvoiceRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PatchedInvoiceRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PatchedInvoiceRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}},"description":""},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}}}}
```

## Perform invoice action

> Perform an action on an invoice using query parameter.\
>     \
>     \*\*Available Actions:\*\*\
>     \- \`send\` - Mark a draft invoice as sent to the client\
>     \- \`mark\_as\_paid\` - Mark an invoice as fully paid\
>     \- \`cancel\` - Cancel an invoice\
>     \- \`duplicate\` - Create a duplicate of the invoice\
>     \- \`record\_payment\` - Record a payment received for the invoice (requires \`amount\` parameter)\
>     \
>     \*\*Examples:\*\*\
>     \- \`/invoices/{id}/action?action=send\`\
>     \- \`/invoices/{id}/action?action=mark\_as\_paid\`\
>     \- \`/invoices/{id}/action?action=cancel\`\
>     \- \`/invoices/{id}/action?action=duplicate\`\
>     \- \`/invoices/{id}/action?action=record\_payment\&amount=1000.00\`\
>     

```json
{"openapi":"3.0.3","info":{"title":"Skhokho API","version":"v1.0"},"tags":[{"name":"Invoices","description":"Invoice creation, management, and tracking"}],"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":{"Invoice":{"type":"object","description":"Comprehensive serializer for Invoice model.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"title":{"type":"string"},"description":{"type":"string","nullable":true},"invoice_number":{"type":"string","maxLength":100},"status":{"enum":["draft","sent","viewed","paid","partially_paid","overdue","cancelled","refunded"],"type":"string","description":"* `draft` - Draft\n* `sent` - Sent\n* `viewed` - Viewed by Client\n* `paid` - Paid\n* `partially_paid` - Partially Paid\n* `overdue` - Overdue\n* `cancelled` - Cancelled\n* `refunded` - Refunded"},"status_display":{"type":"string","readOnly":true},"invoice_date":{"type":"string","format":"date","nullable":true},"due_date":{"type":"string","format":"date"},"subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Calculated from line items"},"total_tax_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Total VAT/tax from all line items"},"total_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$","readOnly":true,"description":"Subtotal + Total Tax Amount"},"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},"currency":{"type":"string","readOnly":true},"client":{"allOf":[{"$ref":"#/components/schemas/FinanceClientMini"}],"readOnly":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"}},"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":["client","created_by","currency","date_created","due_date","invoice_number","is_overdue","last_updated","remaining_amount","status_display","subtotal","title","total_amount","total_tax_amount"]},"FinanceClientMini":{"type":"object","description":"Lightweight serializer for Client model.\nUsed for nested client references in invoices and quotes.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"name":{"type":"string","readOnly":true},"entity_type":{"enum":["individual","company","non_profit","government","partnership","other"],"type":"string","description":"* `individual` - Individual\n* `company` - Company\n* `non_profit` - Non-Profit Organization\n* `government` - Government Entity\n* `partnership` - Partnership\n* `other` - Other"}},"required":["name"]},"InvoiceItem":{"type":"object","description":"Serializer for invoice line items.","properties":{"unique_id":{"type":"string","nullable":true,"maxLength":100},"item_name":{"type":"string","readOnly":true},"quantity":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"unit_price":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,2})?$"},"discount_percentage":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"Discount %"},"vat_rate":{"type":"string","format":"decimal","pattern":"^-?\\d{0,3}(?:\\.\\d{0,2})?$","title":"VAT Rate (%)","description":"VAT/tax rate percentage for this line item"},"currency":{"type":"string","description":"Currency code (ISO 4217) for this line item","maxLength":3},"line_subtotal":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true},"line_vat_amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true},"line_total":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,2})?$","readOnly":true}},"required":["item_name","line_subtotal","line_total","line_vat_amount","quantity","unit_price"]},"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}/invoices/{invoice_id}/action/":{"get":{"operationId":"organisation_invoices_action_retrieve","description":"Perform an action on an invoice using query parameter.\n    \n    **Available Actions:**\n    - `send` - Mark a draft invoice as sent to the client\n    - `mark_as_paid` - Mark an invoice as fully paid\n    - `cancel` - Cancel an invoice\n    - `duplicate` - Create a duplicate of the invoice\n    - `record_payment` - Record a payment received for the invoice (requires `amount` parameter)\n    \n    **Examples:**\n    - `/invoices/{id}/action?action=send`\n    - `/invoices/{id}/action?action=mark_as_paid`\n    - `/invoices/{id}/action?action=cancel`\n    - `/invoices/{id}/action?action=duplicate`\n    - `/invoices/{id}/action?action=record_payment&amount=1000.00`\n    ","summary":"Perform invoice action","parameters":[{"in":"query","name":"action","schema":{"type":"string","enum":["cancel","duplicate","mark_as_paid","record_payment","send"]},"description":"The action to perform on the invoice","required":true},{"in":"query","name":"amount","schema":{"type":"number","format":"double"},"description":"Payment amount (required when action=record_payment)"},{"in":"path","name":"invoice_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":["Invoices"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}},"description":""},"400":{"description":"Bad Request - Invalid action or missing required parameters"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}}}}
```