V4 schema

The V4 schema represents the normalized India GST invoice format returned by /api/ocr-structured-v4. This schema is designed for the Indian GST ecosystem with support for CGST/SGST/IGST tax splits, HSN codes, and reconciliation.

V4Doc Type

The top-level document structure returned by the v4 endpoint.

doc_level

object

required

Document-level metadata

Show properties

supplier_name

string

Supplier/seller name from the invoice

supplier_gstin

string

Supplier’s 15-character GSTIN (e.g., “29AABCU9603R1Z5”)

invoice_number

string

Invoice number or document reference

invoice_date

string

Invoice date in YYYY-MM-DD format

place_of_supply_state_code

string

2-digit state code for place of supply (e.g., “29” for Karnataka)

buyer_gstin

string

Buyer’s 15-character GSTIN

currency

string

Currency code (typically “INR”)

items

V4Item[]

required

Array of line items extracted from the invoice. See V4Item schema below.

header_discounts

object[]

Document-level discounts applied before line-item totals

Show properties

label

string

Discount label (e.g., “Trade Discount”, “Special Discount”)

type

enum

Either “PERCENT” or “ABSOLUTE”

value

number

Discount value (percentage 0-100 or absolute amount)

order

number

Application order for sequential discounts

charges

object[]

Additional charges like shipping, handling, packing

Show properties

label

string

Charge label (e.g., “Freight”, “Packing Charges”)

ex_tax

number

Charge amount excluding GST

gst_rate_hint

number | null

GST rate percentage if applicable

gst_amount

number

GST amount on this charge

inc_tax

number

Total charge including GST

taxable

boolean

Whether this charge is subject to GST

tcs

object

Tax Collected at Source information

Show properties

rate

number

TCS rate percentage

amount

number

TCS amount collected

base_used

string

Description of the base amount TCS was calculated on

round_off

number

Round-off adjustment to arrive at final grand total

totals

object

required

Computed totals after reconciliation

Show properties

items_ex_tax

number

Sum of all line items excluding tax and after discounts

header_discounts_ex_tax

number

Total header-level discount amount

charges_ex_tax

number

Sum of additional charges excluding tax

taxable_ex_tax

number

Total taxable amount before GST

gst_total

number

Total GST amount (CGST + SGST + IGST)

grand_total

number

Final invoice total including all taxes and charges

printed

object

Anchor values printed on the invoice for reconciliation

Show properties

taxable_subtotal

number | null

Taxable subtotal printed on invoice

gst_total

number | null

Total GST amount printed on invoice

hsn_tax_table

array

HSN-wise tax breakup table if present

grand_total

number | null

Grand total printed on invoice

reconciliation

object

required

Reconciliation results and diagnostics

Show properties

error_absolute

number

Absolute difference between computed and printed grand total. Values ≤ ₹0.05 indicate successful reconciliation.

alternates_considered

string[]

List of candidate hypotheses tested during reconciliation

warnings

string[]

Any warnings or issues encountered during reconciliation

V4Item Type

Represents a single line item on the invoice.

name

string

required

Item name or description

hsn

string

required

HSN code (Harmonized System of Nomenclature)

qty

number

required

Quantity

uom

string

required

Unit of measurement (e.g., “PCS”, “KGS”, “BOX”)

rate_ex_tax

number

required

Unit rate excluding tax (best source determined by reconciliation)

discount

object

required

Line-level discount information

Show properties

d1_pct

number | null

First discount percentage (0-100)

d2_pct

number | null

Second discount percentage (0-100)

flat_per_unit

number | null

Flat discount amount per unit

effective_pct

number

Effective combined discount percentage

amount

number

Total discount amount for this line

gst

object

required

GST information for this line item

Show properties

rate

number

GST rate percentage (0, 5, 12, 18, 28)

cgst

number

Central GST amount (intra-state)

sgst

number

State GST amount (intra-state)

igst

number

Integrated GST amount (inter-state)

amount

number

Total GST amount (cgst + sgst + igst)

totals

object

required

Computed line totals

Show properties

line_ex_tax

number

Line total excluding tax (qty × rate_ex_tax - discount)

line_inc_tax

number

Line total including tax

raw

object

Raw extraction data before reconciliation

Show properties

rate_printed

number | null

Rate value printed on invoice

price_mode_detected

enum

Either “WITH_TAX” or “WITHOUT_TAX”

discount_pct_printed

number | null

Discount percentage printed on invoice

special_discount_pct_printed

number | null

Special discount percentage if shown separately

amount_printed

number | null

Line amount printed on invoice

amount_ex_tax_before_discount

number | null

Amount before discounts excluding tax

amount_ex_tax_after_discount

number | null

Amount after discounts excluding tax

ui_hints

object

Display hints for UI rendering (structure varies)

confidence

number

required

Confidence score for this line item (0-1)

Example Response

{
  "doc_level": {
    "supplier_name": "ABC Enterprises",
    "supplier_gstin": "29AABCU9603R1Z5",
    "invoice_number": "INV-2024-001",
    "invoice_date": "2024-03-01",
    "place_of_supply_state_code": "29",
    "buyer_gstin": "27AAPFU0939F1ZV",
    "currency": "INR"
  },
  "items": [
    {
      "name": "Widget A",
      "hsn": "8471",
      "qty": 10,
      "uom": "PCS",
      "rate_ex_tax": 100.00,
      "discount": {
        "d1_pct": 10,
        "d2_pct": null,
        "flat_per_unit": null,
        "effective_pct": 10.00,
        "amount": 100.00
      },
      "gst": {
        "rate": 18,
        "cgst": 81.00,
        "sgst": 81.00,
        "igst": 0,
        "amount": 162.00
      },
      "totals": {
        "line_ex_tax": 900.00,
        "line_inc_tax": 1062.00
      },
      "confidence": 0.95
    }
  ],
  "header_discounts": [],
  "charges": [
    {
      "label": "Freight",
      "ex_tax": 50.00,
      "gst_rate_hint": 18,
      "gst_amount": 9.00,
      "inc_tax": 59.00,
      "taxable": true
    }
  ],
  "tcs": {
    "rate": 0,
    "amount": 0,
    "base_used": ""
  },
  "round_off": -0.50,
  "totals": {
    "items_ex_tax": 900.00,
    "header_discounts_ex_tax": 0,
    "charges_ex_tax": 50.00,
    "taxable_ex_tax": 950.00,
    "gst_total": 171.00,
    "grand_total": 1120.50
  },
  "printed": {
    "taxable_subtotal": 950.00,
    "gst_total": 171.00,
    "hsn_tax_table": [],
    "grand_total": 1121.00
  },
  "reconciliation": {
    "error_absolute": 0.50,
    "alternates_considered": [
      "Candidate 1: price_mode=WITHOUT_TAX, non_taxable_charges=include",
      "Candidate 2: price_mode=WITH_TAX, non_taxable_charges=include"
    ],
    "warnings": []
  },
  "meta": {
    "pages_processed": 1,
    "language": "en",
    "overall_confidence": 0.93
  }
}

OCR Structured V4 Endpoint

Use this schema with the v4 API endpoint

Understanding Reconciliation

Learn how reconciliation works

Reconciliation Engine

Deep dive into the reconciliation algorithm

MyBillBook Schema

Alternative compact schema format

Endpoints

Schemas

V4Doc Type

V4Item Type

Example Response

OCR Structured V4 Endpoint

Understanding Reconciliation

Reconciliation Engine

MyBillBook Schema

Build docs developers (and LLMs) love

Endpoints

Schemas

​V4Doc Type

​V4Item Type

​Example Response

​Related

OCR Structured V4 Endpoint

Understanding Reconciliation

Reconciliation Engine

MyBillBook Schema

Build docs developers (and LLMs) love

V4Doc Type

V4Item Type

Example Response

Related