Documentation
API reference
Try uses this server’s
/v1
(same origin). Integrations use the production base below.
OpenAPI YAML
for codegen.
·
Cursor skill
for AI assistants
(appendix).
localStorage only. Sent as Authorization: Bearer … to this origin.
Meta
/v1/me
Returns the account tied to your API key (id, business name, email, currency, subscription).
Example response
{
"ok": true,
"data": {
"account_id": 1,
"business_name": "Demo Traders",
"business_email": "hello@example.com",
"currency": "INR",
"subscription_expires_at": "2026-12-31 23:59:59"
}
}
Clients
/v1/clients
Paginated clients. Query: limit (max 200, default 50), offset.
Example response
{
"ok": true,
"data": {
"clients": [
{
"client_id": 10,
"name": "Ravi Kumar",
"phone": "9876543210",
"email": "ravi@client.test",
"gstin": null
}
],
"total": 1
}
}
/v1/clients
Create client (name, phone, email required). Optional: address, gstin (15-char format when used). Duplicate phone (10 digits), email, or GSTIN → 200 with data.skipped true and data.client = existing row.
Example response
{
"ok": true,
"data": {
"skipped": false,
"client": {
"client_id": 11,
"name": "Acme Retail Pvt Ltd",
"phone": "9876543210",
"email": "billing@acme.example",
"address": "Shop 12, MG Road, Bengaluru 560001",
"gstin": null,
"state_code": null
}
}
}
/v1/clients/{id}
Single client by id.
Example response
{
"ok": true,
"data": {
"client_id": 10,
"name": "Ravi Kumar",
"phone": "9876543210",
"email": "ravi@client.test"
}
}
/v1/clients/{id}
Partial update (JSON merged).
Example response
{
"ok": true,
"data": {
"client_id": 10,
"name": "Ravi K. (updated)"
}
}
/v1/clients/{id}
Delete client. Query cascade=1 to remove related invoices/quotations/debit notes.
Example response
{
"ok": true,
"data": {
"deleted": true
}
}
Invoices
/v1/invoices
List invoices. Query: limit, offset, client_id. Rows are DB columns (no line items on list).
Example response
{
"ok": true,
"data": {
"invoices": [
{
"invoice_id": 101,
"client_id": 10,
"invoice_number": "INV-2026-0042",
"invoice_date": "2026-03-21",
"payment_due_date": "2026-04-05",
"payment_status": "pending",
"status": "draft",
"currency": "INR"
}
],
"total": 1
}
}
/v1/invoices
Create invoice. Required: client_id, invoice_date, payment_due_date (Y-m-d). Each items[] row needs item_description (non-empty) or the row is skipped. Send tax splits your app already calculated (CGST+SGST for intra-state, or IGST). Optional: discount_type percentage|fixed + discount_value when DB supports it.
Example response
{
"ok": true,
"data": {
"invoice_id": 101,
"message": "created"
}
}
/v1/invoices/{id}
Single invoice: header fields from invoices row plus items[] (invoice_items columns, ordered by item_id).
Example response
{
"ok": true,
"data": {
"invoice_id": 101,
"client_id": 10,
"invoice_number": "INV-2026-0042",
"invoice_date": "2026-03-21",
"payment_due_date": "2026-04-05",
"currency": "INR",
"items": [
{
"item_id": 501,
"invoice_id": 101,
"item_description": "Professional services March",
"hsn_code": "998314",
"quantity": 1,
"rate": 10000,
"tax_rate": 18,
"cgst_amount": 900,
"sgst_amount": 900,
"igst_amount": 0,
"total_amount": 11800
}
]
}
}
/v1/invoices/{id}
Partial update.
Example response
{
"ok": true,
"data": {
"invoice_id": 101
}
}
/v1/invoices/{id}
Delete invoice.
Example response
{
"ok": true,
"data": {
"deleted": true
}
}
Quotations
/v1/quotations
List quotations. Query: limit, offset, client_id. Rows omit line items (use GET /quotations/{id} for items[]).
Example response
{
"ok": true,
"data": {
"quotations": [
{
"quotation_id": 55,
"client_id": 10,
"quotation_number": "QT-2026-0007",
"quotation_date": "2026-03-21",
"validity_date": "2026-04-21",
"approval_status": "pending",
"currency": "INR"
}
],
"total": 1
}
}
/v1/quotations
Create quotation. Required: client_id, quotation_date. validity_date defaults to quotation_date if omitted. items[] uses the same keys as invoice line items; each row must have item_description or it is ignored.
Example response
{
"ok": true,
"data": {
"quotation_id": 55
}
}
/v1/quotations/{id}
Single quotation header plus items[] (quotation_items columns).
Example response
{
"ok": true,
"data": {
"quotation_id": 55,
"client_id": 10,
"quotation_number": "QT-2026-0007",
"quotation_date": "2026-03-21",
"validity_date": "2026-04-21",
"currency": "INR",
"items": [
{
"item_id": 8801,
"quotation_id": 55,
"item_description": "Annual maintenance (quoted)",
"hsn_code": "9987",
"quantity": 1,
"rate": 50000,
"tax_rate": 18,
"cgst_amount": 4500,
"sgst_amount": 4500,
"igst_amount": 0,
"total_amount": 59000
}
]
}
}
/v1/quotations/{id}
Example response
{
"ok": true,
"data": {
"quotation_id": 55
}
}
/v1/quotations/{id}
Example response
{
"ok": true,
"data": {
"deleted": true
}
}
Debit notes
/v1/debit-notes
List debit notes. Query: limit, offset, client_id.
Example response
{
"ok": true,
"data": {
"debit_notes": [
{
"debit_note_id": 7,
"client_id": 10,
"debit_note_number": "DN-3",
"debit_note_date": "2026-03-21",
"currency": "INR"
}
],
"total": 1
}
}
/v1/debit-notes
Create debit note with line items.
Example response
{
"ok": true,
"data": {
"debit_note_id": 7
}
}
/v1/debit-notes/{id}
Debit note with items[] (description, expense_date, amount per line).
Example response
{
"ok": true,
"data": {
"debit_note_id": 7,
"client_id": 10,
"debit_note_date": "2026-03-21",
"currency": "INR",
"items": [
{
"item_id": 120,
"debit_note_id": 7,
"description": "Rate difference adjustment",
"expense_date": "2026-03-21",
"amount": 500
}
]
}
}
/v1/debit-notes/{id}
Example response
{
"ok": true,
"data": {
"debit_note_id": 7
}
}
/v1/debit-notes/{id}
Example response
{
"ok": true,
"data": {
"deleted": true
}
}
Inventory
/v1/inventory
List inventory rows (products/services).
Example response
{
"ok": true,
"data": {
"items": [
{
"inventory_id": 3,
"name": "Widget A",
"type": "product",
"rate": 250,
"quantity": 100,
"tax_rate": 18,
"hsn_code": "1234"
}
],
"total": 1
}
}
/v1/inventory
Create product/service line.
Example response
{
"ok": true,
"data": {
"inventory_id": 3
}
}
/v1/inventory/{id}
Example response
{
"ok": true,
"data": {
"inventory_id": 3,
"name": "Widget A"
}
}
/v1/inventory/{id}
Example response
{
"ok": true,
"data": {
"inventory_id": 3
}
}
/v1/inventory/{id}
Example response
{
"ok": true,
"data": {
"deleted": true
}
}
Expenses
/v1/expenses
List expenses.
Example response
{
"ok": true,
"data": {
"expenses": [
{
"expense_id": 9,
"expense_description": "Office supplies",
"expense_amount": 1200,
"expense_date": "2026-03-20",
"expense_category": "General"
}
],
"total": 1
}
}
/v1/expenses
Create expense.
Example response
{
"ok": true,
"data": {
"expense_id": 9
}
}
/v1/expenses/{id}
Example response
{
"ok": true,
"data": {
"expense_id": 9
}
}
/v1/expenses/{id}
Example response
{
"ok": true,
"data": {
"expense_id": 9
}
}
/v1/expenses/{id}
Example response
{
"ok": true,
"data": {
"deleted": true
}
}
Sendouts
/v1/sendouts
Queue email with PDF for invoice, quotation, or debit-note.
Example response
{
"ok": true,
"data": {
"success": true,
"message": "Email queued",
"queue_id": 42
}
}
Analytics
/v1/analytics/summary
Dashboard-style aggregates (same idea as legacy get-analytics).
Example response
{
"ok": true,
"data": {
"total_invoices": 12,
"total_revenue": 450000,
"note": "Shape matches your live deployment"
}
}