Invoices

Customer invoices with line items, GST split, and journal posting. Item-driven line auto-fill: send { item_id, quantity } and the server hydrates name / rate / tax / HSN from the item master.

Resource shape

{
  "invoice_id":     "inv_abc",
  "invoice_number": "INV-2026-0042",
  "customer_id":    "ct_acme",
  "customer_name":  "Acme Corp",
  "date":           "2026-05-12T00:00:00",
  "due_date":       "2026-06-11T00:00:00",
  "reference_number": "PO-991",
  "place_of_supply": "IN-MH",
  "currency_code":  "INR",
  "exchange_rate":  1.0,

  "line_items": [
    {
      "line_item_id":   "li_1",
      "item_id":        "it_widget",
      "name":           "Widget",
      "description":    "Widget",
      "hsn_or_sac":     "8421",
      "quantity":       2,
      "unit":           "NOS",
      "rate":           100,
      "discount":       0,
      "tax_id":         "tx_gst_18",
      "tax_percentage": 18,
      "item_total":     200
    }
  ],

  "sub_total":     200,
  "tax_total":     36,
  "total":         236,
  "payment_made":  0,
  "balance":       236,

  "status":        "DRAFT",   // DRAFT | SENT | PARTIALLY_PAID | PAID
                              // | OVERDUE | CANCELLED | CREDIT_APPLIED
  "notes":         null,
  "created_time":  "2026-05-12T08:30:00",
  "last_modified_time": "2026-05-12T08:30:00"
}

Query params

Body

Line item shape

Minimum input: either item_id (auto-fills the rest from the item master) or name + rate (ad-hoc line).

{
  "item_id":     "it_widget",   // inherits name / rate / tax_id / hsn from master
  "quantity":    2,
  "rate":        null,           // overrides item.selling_price if set
  "tax_id":      null,           // overrides item.tax_id if set
  "discount":    0,
  "name":        null,
  "hsn_or_sac":  null,
  "unit":        null
}

Example

POST /invoices
Authorization: Bearer aibk_pat_…
Content-Type: application/json
Idempotency-Key: …

{
  "customer_id": "ct_acme",
  "date": "2026-05-12T00:00:00",
  "place_of_supply": "IN-MH",
  "line_items": [{ "item_id": "it_widget", "quantity": 2 }],
  "auto_approve": true
}

Multi-series numbering (CGST Rule 46)

Indian GST allows an organisation to maintain multiple invoice number series per branch — typically one for domestic (default), one for exports (export), one for reverse-charge (rcm), etc. Each series has its own sequence; numbers must be unique within a branch.

1. List available series

Always call this first so your integration knows which series_name values are valid for the active branch. The response always contains at least one entry — a virtual default if no DocumentSequence rows are configured yet.

Query params

Request

curl -X GET 'http://localhost:8000/api/public/v1/invoices/series?branchId=branch_abc' \
  -H 'Authorization: Bearer aibk_pat_…'

Response

{
  "series": [
    {
      "seriesName": "default",     // value to send as series_name when creating
      "label":      "Default",     // display label for your picker UI
      "prefix":     "INV-",        // prefix the numbers will carry
      "isDefault":  true,          // marks the org's chosen default series
      "periodId":   "fp_2026_27"   // the FY period this series belongs to
    },
    {
      "seriesName": "export",
      "label":      "Export",
      "prefix":     "EXP-",
      "isDefault":  false,
      "periodId":   "fp_2026_27"
    },
    {
      "seriesName": "rcm",
      "label":      "RCM",
      "prefix":     "RCM-",
      "isDefault":  false,
      "periodId":   "fp_2026_27"
    }
  ],
  "branchId": "branch_abc"          // the branch the response was resolved for
}

Field reference

2. Numbering precedence

The public API decides which number to apply on POST /invoices in this order:

Unknown series names don't error — the service falls back to legacy date-based numbering. That's why step 1 matters: always discover before you pick.

3. Create with a chosen series

POST /invoices
Authorization: Bearer aibk_pat_…
Content-Type: application/json
Idempotency-Key: …

{
  "customer_id":     "ct_acme",
  "date":            "2026-05-16T00:00:00",
  "place_of_supply": "IN-MH",
  "series_name":     "export",        // value from /invoices/series response
  "branch_id":       "branch_abc",
  "line_items":      [{ "item_id": "it_widget", "quantity": 2 }],
  "auto_approve":    true
}

The response's invoice_number will be the next number from the export sequence, e.g. EXP-2026-0042.

Override — your number wins

POST /invoices

{
  "customer_id":     "ct_acme",
  "date":            "2026-05-16T00:00:00",
  "place_of_supply": "IN-MH",
  "invoice_number":  "MY-CUSTOM-2026-001",  // used as-is, series ignored
  "branch_id":       "branch_abc",
  "line_items":      [{ "item_id": "it_widget", "quantity": 2 }]
}

Note: a custom invoice_number does not advance the series sequence. The next auto-generated invoice on the same series will continue from where the sequence was.

Only reference_number, due_date, and notes are editable, and only while status is DRAFT. To change line items, void and recreate.

Voiding posts the reversal journal automatically. Paid invoices can't be voided directly — reverse the payment first.