Invoice Number Series

Each branch can run multiple invoice number series in parallel (e.g. default, export, rcm). CGST Rule 46 requires each series to be unique per GSTIN. These endpoints let you list, peek next, and create custom series.

List

Query params:

• transactionDate — FY context. Defaults to today.
• branchId — Resolve series for this branch. Falls back to the org's default branch.

curl -H "Authorization: Bearer $PAT" \
  "$BASE/invoices/series?transactionDate=2026-05-19"

# Response
{
  "series": [
    { "seriesName": "default", "label": "Default",  "prefix": "INV-", "isDefault": true,  "periodId": "..." },
    { "seriesName": "export",  "label": "Export",   "prefix": "EXP-", "isDefault": false, "periodId": "..." },
    { "seriesName": "rcm",     "label": "RCM",      "prefix": "RCM-", "isDefault": false, "periodId": "..." }
  ],
  "branchId": "br_main"
}

When no FY accounting period is configured, a single virtual default series is returned so your picker always has at least one entry to bind to.

Peek next number

Query params:

• series — Series name. Default default.
• transactionDate — FY context. Defaults to today.
• branchId — Resolve sequence for this branch.

curl -H "Authorization: Bearer $PAT" \
  "$BASE/invoices/series/next-number?series=export"

{
  "code":        0,
  "message":     "success",
  "next_number": "EXP-2627-001",
  "series":      "export",
  "branch_id":   "br_main"
}

Idempotent — calling it 100 times returns the same number. Only POST /invoices actually increments the counter. Useful for previewing the upcoming number in your own UI before the user clicks Submit.

Create a custom series

POST /invoices/series
{
  "series_name":      "export",        // required, unique per (period, branch)
  "prefix":           "EXP-",          // required
  "label":            "Export Invoices",
  "padding":          3,                // digit padding, default 3
  "format_template":  "{prefix}{fy}-{num}",  // default — keep unless you need custom
  "transaction_date": "2026-05-19",     // optional — locks to the period covering this date
  "branch_id":        "br_main"         // optional — falls back to org default branch
}

# Response
{
  "code": 0,
  "message": "The series has been created.",
  "series": {
    "id":           "ds_…",
    "series_name":  "export",
    "label":        "Export Invoices",
    "prefix":       "EXP-",
    "is_default":   false,
    "period_id":    "...",
    "branch_id":    "br_main"
  }
}

Requires an accounting period covering transaction_date to exist. If none does you get 400 validation.invalid_value with a message explaining the FY-period gap.

Using a series on invoice create

Pass series_name on POST /invoices:

POST /invoices
{
  ...,
  "series_name": "export",      // → consumes the export counter
  "line_items": [...]
}

# Invoice number comes from the export series
{ "invoice_number": "EXP-2627-001", ... }

Use cases

• Multi-branch businesses — branch-scoped series keep numbers unique per GSTIN as required by Rule 46.
• Export vs domestic — most accountants prefer a dedicated EXP- prefix for tax-relief invoices.
• Reverse Charge invoices — sometimes auditors want them on a separate trail, e.g. RCM-.
• Government / SEZ clients — a separate series (GOV-, SEZ-) makes reporting easier.