gst_einvoice

Build and check India GST e-invoice data (INV-01, schema version 1.1) in pure Dart. Use it in Flutter apps (Android, iOS, web, desktop) or on a Dart server. It has no dependencies.

If you build billing, POS or inventory apps for Indian businesses, you need to send invoice data to the government's Invoice Registration Portal (IRP) as JSON. This package helps you get that JSON right before you send it.

What it does

• Gstin: checks the format and checksum of a GSTIN and tells you why it fails.
• GstCalculator: CGST + SGST or IGST, exact to the paisa, including prices that already include GST.
• EInvoice, Party, InvoiceItem: describe an invoice in Dart and get INV-01 JSON with every tax amount and total filled in.
• EInvoiceValidator: checks any INV-01 JSON (yours or from another system) for common mistakes: bad GSTINs, wrong tax split, wrong totals, bad dates, long invoice numbers and more.
• GstStateCodes: state and union-territory code lookup (Gujarat is 24).

What it does not do

• It does not call the IRP or any GSP. You send the JSON yourself.
• It does not create the IRN or the signed QR code. The IRP does that and returns them.
• It is not a copy of NIC's validation. A payload can pass here and still be rejected, so always test with the NIC e-invoice sandbox.
• It is not tax advice. GST rules, rates and the schema change; check the current official documents.

Install

dart pub add gst_einvoice
# or, in a Flutter app
flutter pub add gst_einvoice

Quick start

Check a GSTIN

final result = Gstin.check('27AAPFU0939F1ZV');
print(result.isValid); // true
print(Gstin.check('27AAPFU0939F1ZX').reason); // Checksum is wrong. ...

Work out GST

final line = GstCalculator.forLine(
  quantity: 10,
  unitPrice: 500,
  discount: 500,
  gstRate: 18,
  kind: SupplyKind.intraState, // same state: CGST + SGST
);
print(line.taxable); // 4500.0
print(line.cgst);    // 405.0
print(line.total);   // 5310.0

// A price that already includes GST: 1180 at 18% -> 1000 + 180.
final split = GstCalculator.fromInclusivePrice(
  price: 1180,
  gstRate: 18,
  kind: SupplyKind.interState,
);
print(split.igst); // 180.0

Build and check an invoice

final invoice = EInvoice(
  documentNumber: 'INV/2026-27/0001',
  documentDate: DateTime(2026, 11, 2),
  seller: Party(
    gstin: '24AAAAA0000A1Z8',
    legalName: 'Sample Traders',
    address1: '12 CG Road',
    location: 'Ahmedabad',
    pincode: 380009,
  ),
  buyer: Party(
    gstin: '24BBBBB1111B1ZT',
    legalName: 'Demo Electronics',
    address1: '5 Ring Road',
    location: 'Surat',
    pincode: 395003,
  ),
  items: const [
    InvoiceItem(
      description: 'Wireless Mouse',
      hsnCode: '847160',
      quantity: 10,
      unit: 'NOS',
      unitPrice: 500,
      gstRate: 18,
    ),
  ],
);

final problems = invoice.validate();
if (problems.isEmpty) {
  final json = invoice.toJson(); // send this to the IRP
} else {
  problems.forEach(print); // e.g. "SellerDtls.Gstin: Checksum is wrong. ..."
}

The GSTINs above are made-up test values. HSN codes and the 18% rate are examples: use the real code and the current rate for your item.

Check JSON from somewhere else

final issues = const EInvoiceValidator().validate(jsonMap);
for (final i in issues) {
  print('${i.path}: ${i.message}');
}

Good to know

• Sandbox GSTINs. NIC's test GSTINs (like 29AAFCD5862R000) do not follow the real format. Use EInvoiceValidator(sandbox: true) or Gstin.check(x, sandbox: true) in tests. Never use sandbox mode for real invoices.
• Money is exact. Amounts are calculated in whole paise, then returned as rupees. In intra-state sales CGST and SGST are each rounded half-up on their own.
• Tolerance. The validator allows amounts to differ by tolerance rupees (default 1.0) to allow for rounding. Tune it to the limit NIC currently allows.
• Document-level discount. If ValDtls.Discount is non-zero, the invoice total is not checked, because that rule is not verified in this version.

Roadmap

• Round-off (RndOffAmt) helper
• Cess and other-charge support in the builder
• Credit and debit note helpers (RefDtls)
• Dispatch, ship-to, export and e-way bill sections
• Decoding the signed QR payload from the IRP response
• An optional IRP client with pluggable transport

Ideas and bug reports are welcome in the issue tracker.

License

MIT