# 🧾 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"}}}}}} ``` --- # 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/invoices.md?ask= ``` 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.