Order and GST tax invoices in Go

What it does

Configuration

One setting is required: the seller’s name. All five are Config fields, set in your own main() or through the reference binary’s -invoices flag and its three environment variables. A GST store takes its seller details from the store’s profile under Settings instead, and keeps its Tally ledger names on the Invoices screen.

The module reads its Config struct, not the environment. The variable names are the ones the package’s own example or the reference binary uses; in your own main() you choose where each value comes from. Where a setting has a panel label, the admin’s settings drawer can hold it too, and a value typed there wins over Config.

Setting it up

1. Choose the number formatThe default is INV-{year}-{seq:05}, which gives INV-2026-00001. Settle yours before the first invoice. A plain store’s count restarts each calendar year, a GST store’s on 1 April; INV/{fy}/{seq:05} is the usual Indian shape.
2. Install the moduleImport it and pass invoices.New to gocommerce.New with at least SellerName, as below, or run the reference binary with -invoices and the INVOICES_ variables.
3. For GST, fill in the profileUnder Settings: India, rupees, the GSTIN as the tax registration, the legal name and the address. Give each variant its HS code, which a GST invoice prints as the HSN.
4. Print, fetch or exportOpen an invoice from its order or the Invoices screen, or GET /api/admin/x/invoices/{orderId}: HTML to print, or JSON with Accept: application/json. A GST store downloads its Tally files from the same screen.

import (
	"github.com/itswadesh/gocommerce/core"
	"github.com/itswadesh/gocommerce/ext/invoices"
)

app, err := gocommerce.New(cfg,
	invoices.New(invoices.Config{
		SellerName:   "Example Ltd",
		NumberFormat: "INV-{year}-{seq:05}",
	}),
)

How it works

• Issued on payment, once

  The module subscribes to order.paid. Event delivery is at least once, so a unique constraint on the order id turns a repeated event into a no-op rather than a second invoice. A sample order gets none.

• Gapless, per year

  The number comes from a counter row per year, taken under a lock inside the transaction that writes the invoice. A rollback gives the number back, which a PostgreSQL sequence would not. A GST store counts by financial year, on the store’s clock.

• GST from what checkout charged

  A GST invoice works out no tax of its own: each line’s rate and tax are what checkout charged, and a tax rate can apply to one product. Within a state CGST is half the tax rounded down and SGST or UTGST the rest, so the heads always add up; between states it is all IGST.

• Refused rather than wrong

  A GST invoice whose lines do not add up to the order total, or whose Indian delivery address names no state GST knows, is not issued. The paid order stays without one, logged, until the cause is fixed. Checkout on a GST store refuses a buyer GSTIN that does not parse, and an Indian address with no state.

• A snapshot of the order

  The order is stored as JSON as it stood when the invoice was issued, so later edits to the order do not change the invoice’s lines or totals. A GST invoice keeps its whole document, seller included, as issued.

• Nothing missed at start-up

  When the store starts, the module looks for paid orders with no invoice and issues them: the safety net under at-least-once delivery.

• Tally files that import once

  The export reads only the issued GST documents and adds them up, at most a year at a time. Each voucher carries a REMOTEID, gocommerce:<store>:<invoice number>, so importing the same file again with Tally’s overwrite option replaces vouchers instead of duplicating them. A voucher whose entries do not sum to zero is refused.

• Behind its own rights

  Reading invoices and downloading the Tally files needs invoices.read, which the manager and staff roles hold by default. Setting the Tally ledger names needs invoices.configure, which managers hold.

What it does not do

Read these before an order depends on it. No store is known to run GoCommerce in production yet, so these come from the code, not from anyone’s experience.

• No e-invoices or e-way billsA GST invoice carries no IRN or signed QR code, and no e-way bill is made. Both need an account with a GST Suvidha Provider or the Invoice Registration Portal.
• Delivery without GSTCheckout does not charge GST on delivery, so a GST invoice prints delivery as an untaxed line and flags it for the accountant.
• No credit notesA refund issues nothing and changes nothing: the module listens for order.paid only. There are no GST credit notes, no bills of supply and no cess, and every line’s unit is NOS.
• Tally files not yet importedThe files follow Tally’s published format, but they have not yet been test-imported into TallyPrime itself. Tally’s help does not show a party ledger’s GST registration or a voucher’s GST tags as XML, so the party ledger carries none, and the accountant sets each tax ledger’s duty head in Tally once.
• No tax line on the plain invoiceOutside GST mode, the order’s tax is in the snapshot, but the printed invoice shows subtotal, shipping, discount and total only. With tax-exclusive prices, the lines shown do not add up to the total.
• Minor units on the plain invoiceThe plain invoice prints every amount as a whole number of minor units, INR 123450 for ₹1,234.50, and says so at its foot. The GST invoice prints rupees and paise.
• Plain seller details are read liveOn the plain invoice the seller block comes from Config when the invoice is viewed, not from the snapshot. Change the address and every past plain invoice shows the new one.
• No PDF, no emailThe invoice is an HTML page to print or JSON to process. The module renders no PDF and does not send the invoice to the shopper, and buyers in the dealer portal do not see it.
• 500 at a time on start-upThe start-up catch-up issues invoices for at most 500 paid orders. A larger backlog is cleared over several restarts.

Related modules

Each is a directory under ext/, imported the same way. Where this one fits in the store: How modules extend GoCommerce.

• Open-source ecommerce MCP server in Go Let an AI agent operate a GoCommerce store over the Model Context Protocol: 19 tools, per-tool rights, read-only agent keys, a read-only mode and an audit log.
• Storefront menus API in Go Keep a GoCommerce storefront’s menus as trees of links by handle, saved whole, resolved to storefront paths, and moved in and out as a CSV file.
• Multi-language product catalogue in Go Serve GoCommerce product titles, descriptions and SEO fields in the shopper’s language: the translations module, the store’s languages, what stays untranslated.
• Signed ecommerce webhooks in Go Send a GoCommerce store’s events to another server: register an https URL and the events it wants, and each is POSTed signed, retried with backoff and logged.