Skip to main content
The MyBillBook schema is a compact format returned by /api/ocr-structured. It follows the MyBillBook invoice data structure and is suitable for simpler invoice processing workflows.

​
InvoiceDoc Type

The top-level document structure for the compact schema.
​
voucher
object
required
Invoice header information
​
items
InvoiceItem[]
required
Array of invoice line items (see InvoiceItem below)
​
party
object
required
Buyer/customer information

​
InvoiceItem Type

Represents a single line item in the compact schema.
​
name
string
required
Item name or description
​
hsn_sac_code
string
required
HSN or SAC code
​
quantity
string
required
Quantity as a string
​
unit
string
required
Unit of measurement (e.g., “PCS”, “KGS”)
​
price
string
required
Unit price excluding tax (as a string)
​
tax_rate
string
required
Tax rate percentage (e.g., “18” for 18% GST)
​
discount_rate
string
required
Line-level discount percentage (e.g., “10” for 10% off)

​
AdditionalCharge Type

Represents additional charges like freight, packing, handling fees.
​
name
string
Charge name (alternative to label)
​
label
string
Charge label (alternative to name)
​
amount
string | number
Charge amount as printed (interpretation depends on amount_includes_tax)
​
tax_rate
string | number
Tax rate percentage (may be combined CGST+SGST string like “9+9”)
​
amount_includes_tax
boolean
Whether amount is gross (including tax) or net (excluding tax)
​
ex_tax
string | number
Normalized amount excluding tax (optional v4-style field)
​
inc_tax
string | number
Normalized amount including tax (optional v4-style field)
​
gst_rate
string | number
GST rate (optional v4-style field)
​
gst_rate_hint
string | number | null
GST rate hint for inference (optional v4-style field)
​
gst_amount
string | number
GST amount on this charge (optional v4-style field)
​
taxable
boolean
Whether this charge is subject to tax (optional v4-style field)

​
Example Response

{
  "voucher": {
    "invoice_number": "INV-2024-001",
    "invoice_date": "2024-03-01",
    "invoice_due_date": "2024-03-31",
    "invoice_discount": "50",
    "invoice_discount_mode": "before_tax",
    "round_off": "-0.50",
    "total_invoice_amount": "1180.50",
    "additional_charges": [
      {
        "name": "Freight",
        "amount": "100",
        "tax_rate": "18",
        "amount_includes_tax": false
      }
    ]
  },
  "items": [
    {
      "name": "Widget A",
      "hsn_sac_code": "8471",
      "quantity": "10",
      "unit": "PCS",
      "price": "100",
      "tax_rate": "18",
      "discount_rate": "10"
    },
    {
      "name": "Widget B",
      "hsn_sac_code": "8472",
      "quantity": "5",
      "unit": "PCS",
      "price": "50",
      "tax_rate": "12",
      "discount_rate": "0"
    }
  ],
  "party": {
    "party_gstin_number": "27AAPFU0939F1ZV",
    "party_name": "XYZ Corp",
    "party_address": "123 Main Street",
    "party_city": "Mumbai",
    "party_pincode": "400001",
    "party_pan_number": "AAPFU0939F"
  }
}

​
Reconciliation

The compact schema can be processed through reconciliation logic (see lib/invoice.ts:reconcileInvoice) which:
  1. Computes line-level totals from quantity, price, discount, and tax
  2. Applies invoice-level discounts (before or after tax)
  3. Adds additional charges with tax handling
  4. Tests multiple hypotheses to match the printed total
The reconciliation engine for this schema is separate from the V4 reconciliation engine. For more advanced reconciliation with HSN table anchoring and multi-hypothesis testing, use the V4 schema.

​
Comparison with V4 Schema

FeatureMyBillBook SchemaV4 Schema
FormatCompact, string-basedNormalized, number-based
Discount typesSingle percentage per lineMultiple sequential discounts (d1, d2, flat)
Tax representationCombined rate stringSeparate CGST/SGST/IGST amounts
ReconciliationSimple hypothesis testing6-phase multi-candidate algorithm
HSN anchoringNot supportedSupported via HSN tax table
Use caseSimpler invoices, basic extractionComplex GST invoices, audit-ready data

​
When to Use This Schema

Use the MyBillBook schema when:
  • You need a simple, compact JSON format
  • You’re integrating with systems expecting MyBillBook format
  • Invoice complexity is low (no complex discounting schemes)
  • You don’t need detailed GST breakdowns
Use the V4 schema when:
  • You need HSN-wise tax reconciliation
  • Invoices have complex discount structures
  • You need separate CGST/SGST/IGST amounts
  • Accuracy and audit compliance are critical

OCR Structured Endpoint

Use this schema with the structured API endpoint

V4 Schema

Alternative normalized schema with advanced reconciliation

Request Formats

Learn how to format API requests

Understanding Reconciliation

How reconciliation works for both schemas

Build docs developers (and LLMs) love

Get started for freeTalk to us